@kubun/connector-google-calendar 0.17.2 → 0.17.3

package/lib/api.d.ts

@@ -1,6 +1,7 @@
 import { type EntityRecord } from '@kubun/connector';
+import { type GoogleAPIClient } from '@kubun/provider-google';
 export { type ConnectorErrorKind, classifyHTTPStatus } from '@kubun/connector';
-export declare function parseGoogleError(response: Response): Promise<string>;
+export declare function calendarAPIClient(accessToken: string, fetch?: typeof globalThis.fetch): GoogleAPIClient;
 export type GoogleCalendarResource = {
     id: string;
     summary: string;

package/lib/api.js

@@ -1,22 +1,16 @@
 import { connectorHTTPError } from '@kubun/connector';
+import { createGoogleAPIClient } from '@kubun/provider-google';
 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 {
-        const body = await response.json();
-        return body.error?.message ?? `${response.status} ${response.statusText}`;
-    } catch  {
-        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);
+export function calendarAPIClient(accessToken, fetch) {
+    return createGoogleAPIClient({
+        api: 'Google Calendar API',
+        accessToken,
+        fetch,
+        toError: ({ httpStatus, message })=>connectorHTTPError(message, httpStatus)
+    });
 }
 /**
  * A create that collided with an existing event it could not confirm as its
@@ -158,18 +152,8 @@ export function buildEventFromParams(params, options) {
 // 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}/users/me/calendarList/${encodeURIComponent(config.calendarID)}`;
-    const response = await fetchFn(url, {
-        headers: {
-            Authorization: `Bearer ${config.accessToken}`
-        }
-    });
-    if (!response.ok) {
-        const errorMessage = await parseGoogleError(response);
-        throw googleAPIError(response.status, errorMessage);
-    }
-    return await response.json();
+    return calendarAPIClient(config.accessToken, config.fetch).get(url);
 }
 // A composite calendarID/eventID sourceID splits on the LAST '/': an eventID
 // never contains one, but a calendarID (email-like) may.
@@ -184,18 +168,8 @@ export function splitEventSourceID(sourceID) {
     };
 }
 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, {
-        headers: {
-            Authorization: `Bearer ${config.accessToken}`
-        }
-    });
-    if (!response.ok) {
-        const errorMessage = await parseGoogleError(response);
-        throw googleAPIError(response.status, errorMessage);
-    }
-    return await response.json();
+    return calendarAPIClient(config.accessToken, config.fetch).get(url);
 }
 export async function getEvent(config) {
     const data = await fetchEventResource(config);
@@ -212,20 +186,16 @@ export async function getEventWithETag(config) {
     };
 }
 export async function createEvent(config) {
-    const fetchFn = config.fetch ?? globalThis.fetch;
+    const client = calendarAPIClient(config.accessToken, config.fetch);
     const event = buildEventFromParams(config.params, {
         create: true,
         eventID: config.eventID
     });
     const eventID = event.id;
     const url = `${CALENDAR_BASE_URL}/calendars/${encodeURIComponent(config.calendarID)}/events`;
-    const response = await fetchFn(url, {
+    const response = await client.request(url, {
         method: 'POST',
-        headers: {
-            Authorization: `Bearer ${config.accessToken}`,
-            'Content-Type': 'application/json'
-        },
-        body: JSON.stringify(event)
+        body: event
     });
     if (!response.ok) {
         // A 409 on a caller-chosen id means an event already exists under it. It
@@ -254,31 +224,20 @@ export async function createEvent(config) {
             }
             return existing;
         }
-        const errorMessage = await parseGoogleError(response);
-        throw googleAPIError(response.status, errorMessage);
+        return client.fail(response);
     }
     const data = await response.json();
     return mapEventToEntity(data, config.calendarID);
 }
 export async function updateEvent(config) {
-    const fetchFn = config.fetch ?? globalThis.fetch;
     const event = buildEventFromParams(config.params);
     const url = `${CALENDAR_BASE_URL}/calendars/${encodeURIComponent(config.calendarID)}/events/${encodeURIComponent(config.eventID)}`;
-    const response = await fetchFn(url, {
+    const data = await calendarAPIClient(config.accessToken, config.fetch).send(url, {
         method: 'PATCH',
-        headers: {
-            Authorization: `Bearer ${config.accessToken}`,
-            'Content-Type': 'application/json',
-            ...config.etag != null ? {
-                'If-Match': config.etag
-            } : {}
-        },
-        body: JSON.stringify(event)
+        body: event,
+        headers: config.etag != null ? {
+            'If-Match': config.etag
+        } : {}
     });
-    if (!response.ok) {
-        const errorMessage = await parseGoogleError(response);
-        throw googleAPIError(response.status, errorMessage);
-    }
-    const data = await response.json();
     return mapEventToEntity(data, config.calendarID);
 }

package/lib/errors.d.ts

@@ -20,13 +20,3 @@ export declare class GoogleCalendarEventConflict extends GoogleCalendarError {
     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

@@ -29,18 +29,3 @@ import { ConnectorError } from '@kubun/connector';
         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/index.d.ts

@@ -1,7 +1,7 @@
 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 { 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';

package/lib/index.js

@@ -1,7 +1,7 @@
 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 { GoogleCalendarError, GoogleCalendarEventConflict } from './errors.js';
 export { deriveEventID } from './event-id.js';
 export { canonicalizeEventIntent, eventHoldsIntent } from './intent.js';
 export { googleCalendarClusters, googleCalendarDefinition, googleCalendarEventDefinition } from './model.js';

package/lib/model.d.ts

@@ -41,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";
@@ -59,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: {};
@@ -131,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";
@@ -165,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: {

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',
@@ -52,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
         }
     },
@@ -150,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: {
@@ -164,8 +146,6 @@ export const googleCalendarEventDefinition = {
                 minLength: 1,
                 maxLength: 1400
             },
-            SourceURL: urlSchema,
-            DateTime: dateTimeSchema,
             TimeZone: timeZoneSchema,
             HtmlLink: urlSchema,
             CalendarDocID: docIDSchema,

package/lib/provider.js

@@ -1,30 +1,12 @@
-import { resolveModelID } from '@kubun/connector';
+import { ConnectorError, fetchOrAbsent, parseMaxAgeDays, resolveModelID } from '@kubun/connector';
 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 { 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');
-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();
@@ -37,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,
@@ -57,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
@@ -68,18 +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;
-    // 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
@@ -91,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){
@@ -123,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
             })){
@@ -198,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
         })){
@@ -263,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
@@ -335,41 +312,32 @@ export function createGoogleCalendarProvider(config) {
     // 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({
+        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: sourceID,
+                    calendarID,
+                    eventID,
                     fetch: fetchFn
                 });
                 return {
-                    present: true,
-                    record: mapCalendarToEntity(calendar, accountKey),
-                    sourceFetchHLC
+                    record
                 };
             }
-            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
@@ -377,44 +345,33 @@ export function createGoogleCalendarProvider(config) {
     // condition on.
     async function reconcile(model, sourceID) {
         const sourceFetchHLC = mintFetchHLC();
-        try {
-            if (model === CALENDAR_MODEL_ID) {
-                const calendar = await getCalendarListEntry({
+        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: sourceID,
+                    calendarID,
+                    eventID,
                     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 ? {
+                    record,
                     providerETag: etag
-                } : {}
-            };
-        } catch (err) {
-            if (isNotFound(err)) {
-                return {
-                    present: false,
-                    sourceID,
-                    sourceFetchHLC
                 };
             }
-            throw err;
-        }
+        });
     }
     return {
         supportedStrategies: [
@@ -434,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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kubun/connector-google-calendar",
-  "version": "0.17.2",
+  "version": "0.17.3",
   "keywords": [],
   "license": "see LICENSE.md",
   "sideEffects": false,
@@ -15,13 +15,13 @@
     "LICENSE.md"
   ],
   "dependencies": {
-    "@kubun/connector": "^0.17.2",
+    "@kubun/connector": "^0.17.3",
     "@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.1",
-    "@kubun/provider-google": "^0.17.0",
+    "@kubun/protocol": "^0.17.2",
+    "@kubun/provider-google": "^0.17.1",
     "@kubun/scalars": "^0.17.0",
     "@sozai/codec": "^0.4.0"
   },