@memberjunction/communication-gmail 6.2.0-edge.4 → 6.2.0-edge.6

package/dist/GmailProvider.js

@@ -5,17 +5,20 @@ var __decorate = (this && this.__decorate) || function (decorators, target, key,
     return c > 3 && r && Object.defineProperty(target, key, r), r;
 };
 import { UUIDsEqual } from '@memberjunction/global';
-import { BaseCommunicationProvider, CombineFilterClauses, ParseEmailAddressList, resolveCredentialValue, validateRequiredCredentials } from "@memberjunction/communication-types";
+import { BaseCommunicationProvider, CombineFilterClauses, ParseEmailAddressList, resolveCredentialValue, validateRequiredCredentials, CalendarTargetError, CalendarUpdateError } from "@memberjunction/communication-types";
 import { RegisterClass, MJLruCache } from "@memberjunction/global";
 import { LogError, LogStatus } from "@memberjunction/core";
 import * as Config from "./config.js";
 import googleApis from 'googleapis';
+import { BuildGoogleEventBody, ToCalendarChange, ToCalendarEvent } from "./calendar.js";
 /**
  * Gmail's mailbox watch (a `users.watch` registration) expires after roughly 7 days,
  * so the consumer MUST re-watch before then. Expressed in minutes (7 × 24 × 60) to match
  * {@link SubscriptionCapabilities.MaxLifetimeMinutes}.
  */
 const GMAIL_MAX_SUBSCRIPTION_MINUTES = 10080;
+/** A guard against a misbehaving sync stream, not a real limit. */
+const GOOGLE_MAX_SYNC_PAGES = 1000;
 /**
  * Implementation of the Gmail provider for sending and receiving messages
  */
@@ -76,7 +79,7 @@ let GmailProvider = class GmailProvider extends BaseCommunicationProvider {
         };
     }
     /**
-     * Creates a Gmail client with the given credentials
+     * Creates a Gmail client with the given credentials, keeping its OAuth2 client for the calendar
      */
     createGmailClient(creds) {
         // Create OAuth2 client
@@ -86,10 +89,11 @@ let GmailProvider = class GmailProvider extends BaseCommunicationProvider {
             refresh_token: creds.refreshToken
         });
         // Create Gmail API client
-        return googleApis.google.gmail({
+        const client = googleApis.google.gmail({
             version: 'v1',
             auth: oauth2Client
         });
+        return { client, userEmail: null, auth: oauth2Client };
     }
     /**
      * Gets a Gmail client for the given credentials, using caching for efficiency
@@ -101,10 +105,7 @@ let GmailProvider = class GmailProvider extends BaseCommunicationProvider {
             creds.refreshToken === Config.GMAIL_REFRESH_TOKEN;
         if (isEnvCredentials) {
             if (!this.envGmailClient) {
-                this.envGmailClient = {
-                    client: this.createGmailClient(creds),
-                    userEmail: null
-                };
+                this.envGmailClient = this.createGmailClient(creds);
             }
             return this.envGmailClient;
         }
@@ -112,10 +113,7 @@ let GmailProvider = class GmailProvider extends BaseCommunicationProvider {
         const cacheKey = `${creds.clientId}:${creds.refreshToken.substring(0, 10)}`;
         let cached = this.clientCache.Get(cacheKey);
         if (!cached) {
-            cached = {
-                client: this.createGmailClient(creds),
-                userEmail: null
-            };
+            cached = this.createGmailClient(creds);
             this.clientCache.Set(cacheKey, cached);
         }
         return cached;
@@ -639,7 +637,7 @@ let GmailProvider = class GmailProvider extends BaseCommunicationProvider {
     // ========================================================================
     /**
      * Returns the list of operations supported by the Gmail provider.
-     * Gmail supports all operations through its label-based system.
+     * Gmail supports all mailbox and Google Calendar v3 operations.
      */
     getSupportedOperations() {
         return [
@@ -660,9 +658,586 @@ let GmailProvider = class GmailProvider extends BaseCommunicationProvider {
             'CreateSubscription',
             'RenewSubscription',
             'DeleteSubscription',
-            'ParseNotification'
+            'ParseNotification',
+            'CreateEvent',
+            'UpdateEvent',
+            'CancelEvent',
+            'GetEvent',
+            'SyncEvents',
+            'GetEvents',
+            'GetFreeBusy',
+            'CreateCalendarEvent',
+            'UpdateCalendarEvent',
+            'RespondToCalendarEvent',
+            'CancelCalendarEvent',
+            'VerifyMailboxAccess'
         ];
     }
+    /**
+     * Creates an authenticated Google Calendar v3 client using the same OAuth2 credentials.
+     */
+    createCalendarClient(creds) {
+        const oauth2Client = new googleApis.google.auth.OAuth2(creds.clientId, creds.clientSecret, creds.redirectUri);
+        oauth2Client.setCredentials({
+            refresh_token: creds.refreshToken
+        });
+        return googleApis.google.calendar({
+            version: 'v3',
+            auth: oauth2Client
+        });
+    }
+    /**
+     * Normalizes a Google Calendar v3 event into MJ's GetEventsEvent format.
+     */
+    toGetEventsEvent(raw) {
+        const startRaw = raw.start?.dateTime ?? raw.start?.date ?? null;
+        const endRaw = raw.end?.dateTime ?? raw.end?.date ?? null;
+        const startDate = startRaw ? new Date(startRaw) : null;
+        const endDate = endRaw ? new Date(endRaw) : null;
+        const organizer = raw.organizer?.email?.trim().toLowerCase() || undefined;
+        const attendees = (raw.attendees ?? [])
+            .map((a) => a.email?.trim().toLowerCase())
+            .filter((a) => !!a && a !== organizer);
+        return {
+            ExternalSystemRecordID: raw.id ?? '',
+            SeriesID: raw.recurringEventId ?? null,
+            Subject: raw.summary ?? '',
+            Body: raw.description ?? '',
+            StartTime: startDate && !Number.isNaN(startDate.getTime()) ? startDate : null,
+            EndTime: endDate && !Number.isNaN(endDate.getTime()) ? endDate : null,
+            Location: raw.location ?? null,
+            Organizer: organizer,
+            Attendees: [...new Set(attendees)],
+            IsCancelled: raw.status === 'cancelled'
+        };
+    }
+    /**
+     * Lists calendar events from Google Calendar v3 (`calendar.events.list`).
+     */
+    async GetEvents(params, credentials) {
+        try {
+            const creds = this.resolveCredentials(credentials);
+            const calendar = this.createCalendarClient(creds);
+            const calendarId = params.Identifier || params.ContextData?.Email || 'primary';
+            const expand = Boolean(params.StartDateTime && params.EndDateTime);
+            const response = await calendar.events.list({
+                calendarId,
+                timeMin: params.StartDateTime?.toISOString(),
+                timeMax: params.EndDateTime?.toISOString(),
+                singleEvents: expand,
+                orderBy: expand ? 'startTime' : 'updated',
+                showDeleted: Boolean(params.IncludeCancelled),
+                maxResults: params.NumEvents
+            });
+            const items = response?.data?.items ?? [];
+            return {
+                Success: true,
+                Events: items.map((e) => this.toGetEventsEvent(e)),
+                RecurrenceExpanded: expand,
+                SourceData: items
+            };
+        }
+        catch (error) {
+            const errorMessage = error instanceof Error ? error.message : String(error);
+            LogError('Error getting calendar events via Google Calendar', undefined, error);
+            return {
+                Success: false,
+                Events: [],
+                ErrorMessage: `Google Calendar read failed: ${errorMessage}`
+            };
+        }
+    }
+    /**
+     * Queries free/busy schedule intervals across one or more Google Calendars
+     * via `calendar.freebusy.query`.
+     */
+    async GetFreeBusy(params, credentials) {
+        if (!params.Schedules || params.Schedules.length === 0) {
+            return {
+                Success: false,
+                Schedules: [],
+                ErrorMessage: 'GetFreeBusy requires at least one email address in Schedules.'
+            };
+        }
+        try {
+            const creds = this.resolveCredentials(credentials);
+            const calendar = this.createCalendarClient(creds);
+            const response = await calendar.freebusy.query({
+                requestBody: {
+                    timeMin: params.StartDateTime.toISOString(),
+                    timeMax: params.EndDateTime.toISOString(),
+                    items: params.Schedules.map((id) => ({ id }))
+                }
+            });
+            const calendarsMap = response?.data?.calendars ?? {};
+            const schedules = params.Schedules.map((scheduleId) => {
+                const calEntry = calendarsMap[scheduleId];
+                const busyList = calEntry?.busy ?? [];
+                const errors = calEntry?.errors ?? [];
+                const slots = [];
+                for (const interval of busyList) {
+                    if (!interval.start || !interval.end)
+                        continue;
+                    slots.push({
+                        StartTime: new Date(interval.start),
+                        EndTime: new Date(interval.end),
+                        Status: 'Busy'
+                    });
+                }
+                return {
+                    ScheduleID: scheduleId,
+                    Slots: slots,
+                    Error: errors.length > 0 ? errors.map((e) => e.reason ?? 'error').join(', ') : undefined
+                };
+            });
+            return {
+                Success: true,
+                Schedules: schedules,
+                SourceData: [response?.data]
+            };
+        }
+        catch (error) {
+            const errorMessage = error instanceof Error ? error.message : String(error);
+            LogError('Error getting free/busy via Google Calendar', undefined, error);
+            return {
+                Success: false,
+                Schedules: [],
+                ErrorMessage: `Error getting free/busy schedule: ${errorMessage}`
+            };
+        }
+    }
+    /**
+     * Creates a Google Calendar event via `calendar.events.insert`.
+     */
+    async CreateCalendarEvent(params, credentials) {
+        try {
+            const creds = this.resolveCredentials(credentials);
+            const calendarId = params.Identifier || params.ContextData?.Email || 'primary';
+            const requestBody = {
+                summary: params.Subject,
+                description: params.Body,
+                location: params.Location,
+                start: {
+                    dateTime: params.StartTime.toISOString(),
+                    timeZone: params.TimeZone ?? 'UTC'
+                },
+                end: {
+                    dateTime: params.EndTime.toISOString(),
+                    timeZone: params.TimeZone ?? 'UTC'
+                },
+                attendees: params.Attendees?.map((a) => ({
+                    email: a.Email,
+                    displayName: a.Name,
+                    optional: a.Required === false
+                }))
+            };
+            if (params.IsOnlineMeeting) {
+                requestBody.conferenceData = {
+                    createRequest: {
+                        requestId: `mj-${Date.now()}`
+                    }
+                };
+            }
+            if (params.DryRun) {
+                LogStatus(`[DryRun] Google Calendar: CreateCalendarEvent '${params.Subject}' for ${calendarId} — external call skipped`);
+                return {
+                    Success: true,
+                    DryRun: true,
+                    Event: {
+                        ExternalSystemRecordID: 'DRY_RUN_EVENT_ID',
+                        SeriesID: null,
+                        Subject: params.Subject,
+                        Body: params.Body ?? '',
+                        StartTime: params.StartTime,
+                        EndTime: params.EndTime,
+                        Location: params.Location ?? null,
+                        Organizer: calendarId.toLowerCase(),
+                        Attendees: (params.Attendees ?? []).map((a) => a.Email.toLowerCase()),
+                        IsCancelled: false
+                    },
+                    SourceData: requestBody
+                };
+            }
+            const calendar = this.createCalendarClient(creds);
+            const response = await calendar.events.insert({
+                calendarId,
+                conferenceDataVersion: params.IsOnlineMeeting ? 1 : 0,
+                requestBody
+            });
+            const created = response?.data;
+            return {
+                Success: true,
+                Event: created ? this.toGetEventsEvent(created) : undefined,
+                OnlineMeetingUrl: created?.hangoutLink ?? created?.conferenceData?.entryPoints?.[0]?.uri ?? null,
+                SourceData: created
+            };
+        }
+        catch (error) {
+            const errorMessage = error instanceof Error ? error.message : String(error);
+            LogError('Error creating calendar event via Google Calendar', undefined, error);
+            return {
+                Success: false,
+                ErrorMessage: `Error creating calendar event: ${errorMessage}`
+            };
+        }
+    }
+    /**
+     * Updates an existing Google Calendar event via `calendar.events.patch`.
+     */
+    async UpdateCalendarEvent(params, credentials) {
+        try {
+            const creds = this.resolveCredentials(credentials);
+            const calendarId = params.Identifier || params.ContextData?.Email || 'primary';
+            const requestBody = {};
+            if (params.Subject !== undefined)
+                requestBody.summary = params.Subject;
+            if (params.Body !== undefined)
+                requestBody.description = params.Body;
+            if (params.Location !== undefined)
+                requestBody.location = params.Location;
+            if (params.StartTime) {
+                requestBody.start = {
+                    dateTime: params.StartTime.toISOString(),
+                    timeZone: params.TimeZone ?? 'UTC'
+                };
+            }
+            if (params.EndTime) {
+                requestBody.end = {
+                    dateTime: params.EndTime.toISOString(),
+                    timeZone: params.TimeZone ?? 'UTC'
+                };
+            }
+            if (params.Attendees) {
+                requestBody.attendees = params.Attendees.map((a) => ({
+                    email: a.Email,
+                    displayName: a.Name,
+                    optional: a.Required === false
+                }));
+            }
+            if (params.DryRun) {
+                LogStatus(`[DryRun] Google Calendar: UpdateCalendarEvent '${params.EventID}' for ${calendarId} — external call skipped`);
+                return {
+                    Success: true,
+                    DryRun: true,
+                    SourceData: requestBody
+                };
+            }
+            const calendar = this.createCalendarClient(creds);
+            const response = await calendar.events.patch({
+                calendarId,
+                eventId: params.EventID,
+                requestBody
+            });
+            return {
+                Success: true,
+                Event: response?.data ? this.toGetEventsEvent(response.data) : undefined,
+                SourceData: response?.data
+            };
+        }
+        catch (error) {
+            const errorMessage = error instanceof Error ? error.message : String(error);
+            LogError('Error updating calendar event via Google Calendar', undefined, error);
+            return {
+                Success: false,
+                ErrorMessage: `Error updating calendar event: ${errorMessage}`
+            };
+        }
+    }
+    /**
+     * Responds to a Google Calendar event invitation by updating the attendee's responseStatus.
+     */
+    async RespondToCalendarEvent(params, credentials) {
+        try {
+            const creds = this.resolveCredentials(credentials);
+            const calendarId = params.Identifier || params.ContextData?.Email || 'primary';
+            if (params.DryRun) {
+                LogStatus(`[DryRun] Google Calendar: RespondToCalendarEvent (${params.Response}) '${params.EventID}' for ${calendarId} — external call skipped`);
+                return { Success: true, DryRun: true };
+            }
+            const responseStatus = params.Response === 'Accept'
+                ? 'accepted'
+                : params.Response === 'TentativelyAccept'
+                    ? 'tentative'
+                    : 'declined';
+            const calendar = this.createCalendarClient(creds);
+            const existing = await calendar.events.get({
+                calendarId,
+                eventId: params.EventID
+            });
+            const attendees = [...(existing?.data?.attendees ?? [])];
+            const targetEmail = calendarId.toLowerCase();
+            let matched = false;
+            for (const att of attendees) {
+                if (att.self || (att.email && att.email.toLowerCase() === targetEmail)) {
+                    att.responseStatus = responseStatus;
+                    if (params.Comment) {
+                        att.comment = params.Comment;
+                    }
+                    matched = true;
+                }
+            }
+            if (!matched && targetEmail.includes('@')) {
+                attendees.push({
+                    email: calendarId,
+                    responseStatus,
+                    comment: params.Comment
+                });
+            }
+            await calendar.events.patch({
+                calendarId,
+                eventId: params.EventID,
+                sendUpdates: params.SendResponse === false ? 'none' : 'all',
+                requestBody: { attendees }
+            });
+            return { Success: true };
+        }
+        catch (error) {
+            const errorMessage = error instanceof Error ? error.message : String(error);
+            LogError('Error responding to calendar event via Google Calendar', undefined, error);
+            return {
+                Success: false,
+                ErrorMessage: `Error responding to calendar event: ${errorMessage}`
+            };
+        }
+    }
+    /**
+     * Cancels (deletes) a Google Calendar event via `calendar.events.delete`.
+     */
+    async CancelCalendarEvent(params, credentials) {
+        try {
+            const creds = this.resolveCredentials(credentials);
+            const calendarId = params.Identifier || params.ContextData?.Email || 'primary';
+            if (params.DryRun) {
+                LogStatus(`[DryRun] Google Calendar: CancelCalendarEvent '${params.EventID}' for ${calendarId} — external call skipped`);
+                return { Success: true, DryRun: true };
+            }
+            const calendar = this.createCalendarClient(creds);
+            await calendar.events.delete({
+                calendarId,
+                eventId: params.EventID,
+                sendUpdates: 'all'
+            });
+            return { Success: true };
+        }
+        catch (error) {
+            const errorMessage = error instanceof Error ? error.message : String(error);
+            LogError('Error cancelling calendar event via Google Calendar', undefined, error);
+            return {
+                Success: false,
+                ErrorMessage: `Error cancelling calendar event: ${errorMessage}`
+            };
+        }
+    }
+    /**
+     * Verifies whether the active Gmail / Google Workspace credential has access to
+     * the specified mailbox and/or calendar.
+     */
+    async VerifyMailboxAccess(params, credentials) {
+        const identifier = params.Identifier?.trim();
+        if (!identifier) {
+            return {
+                Success: false,
+                Identifier: '',
+                CanReadMail: false,
+                CanReadCalendar: false,
+                ErrorMessage: 'VerifyMailboxAccess requires a non-empty Identifier (mailbox email).'
+            };
+        }
+        try {
+            const creds = this.resolveCredentials(credentials);
+            const cached = this.getGmailClient(creds);
+            const checkMail = params.CheckMailRead ?? true;
+            const checkCalendar = params.CheckCalendarRead ?? true;
+            let canReadMail = false;
+            let canReadCalendar = false;
+            let mailErrorMessage;
+            let calendarErrorMessage;
+            if (checkMail) {
+                try {
+                    const profile = await cached.client.users.getProfile({ userId: 'me' });
+                    const profileEmail = profile?.data?.emailAddress?.trim().toLowerCase();
+                    if (profileEmail && profileEmail !== identifier.toLowerCase()) {
+                        canReadMail = false;
+                        mailErrorMessage = `Authenticated Gmail profile (${profileEmail}) does not match target mailbox (${identifier}).`;
+                    }
+                    else {
+                        canReadMail = true;
+                    }
+                }
+                catch (mailEx) {
+                    mailErrorMessage = mailEx instanceof Error ? mailEx.message : String(mailEx);
+                }
+            }
+            if (checkCalendar) {
+                try {
+                    const calendar = this.createCalendarClient(creds);
+                    await calendar.calendars.get({ calendarId: identifier });
+                    canReadCalendar = true;
+                }
+                catch (calEx) {
+                    calendarErrorMessage = calEx instanceof Error ? calEx.message : String(calEx);
+                }
+            }
+            const overallSuccess = (!checkMail || canReadMail) &&
+                (!checkCalendar || canReadCalendar);
+            return {
+                Success: overallSuccess,
+                Identifier: identifier,
+                CanReadMail: canReadMail,
+                CanReadCalendar: canReadCalendar,
+                MailErrorMessage: mailErrorMessage,
+                CalendarErrorMessage: calendarErrorMessage,
+                ErrorMessage: overallSuccess
+                    ? undefined
+                    : [mailErrorMessage, calendarErrorMessage].filter(Boolean).join('; ')
+            };
+        }
+        catch (error) {
+            const errorMessage = error instanceof Error ? error.message : String(error);
+            return {
+                Success: false,
+                Identifier: identifier,
+                CanReadMail: false,
+                CanReadCalendar: false,
+                ErrorMessage: `Error verifying mailbox access for ${identifier}: ${errorMessage}`
+            };
+        }
+    }
+    // ========================================================================
+    // GOOGLE CALENDAR
+    // On this provider rather than a separate one because it is the same Google account and the same
+    // OAuth2 client: the `MJ: Communication Providers` row named 'Gmail' already stands for the
+    // account, and a calendar link points at that row. The calendar client is built from the same
+    // OAuth2 client on first use.
+    //
+    // SCOPES: the refresh token must carry https://www.googleapis.com/auth/calendar.events (or the
+    // broader .../auth/calendar). A token consented for Gmail scopes only gets 403 here, and the account
+    // has to consent again with the calendar scope added.
+    //
+    // WHOSE CALENDAR: the refresh token decides the account, and Target.Identifier names the calendar.
+    // Target.CalendarID defaults to Target.Identifier, not 'primary': a Google account's primary
+    // calendar ID is its address, so for the token's own account the two are the same calendar, and for
+    // anyone else Google answers 404 instead of writing into the token owner's calendar (the deployment
+    // default these operations must never fall back to).
+    // ========================================================================
+    /** Inserts an event and sends invitations to its attendees (`sendUpdates: 'all'`). */
+    async CreateEvent(params, credentials) {
+        return this.calendarCall('CreateEvent', params.Target, credentials, (message) => ({ Success: false, ErrorMessage: message }), async (calendar, calendarId) => {
+            const response = await calendar.events.insert({
+                calendarId,
+                sendUpdates: 'all',
+                ...(params.Event.IsOnlineMeeting ? { conferenceDataVersion: 1 } : {}),
+                requestBody: BuildGoogleEventBody(params.Event)
+            });
+            return { Success: true, Event: ToCalendarEvent(response.data) };
+        });
+    }
+    /** Patches the given fields and sends the update to attendees. */
+    async UpdateEvent(params, credentials) {
+        const changeError = CalendarUpdateError(params.Changes);
+        if (changeError)
+            return { Success: false, ErrorMessage: changeError };
+        return this.calendarCall('UpdateEvent', params.Target, credentials, (message) => ({ Success: false, ErrorMessage: message }), async (calendar, calendarId) => {
+            const response = await calendar.events.patch({
+                calendarId,
+                eventId: params.ExternalEventID,
+                sendUpdates: 'all',
+                ...(params.Changes.IsOnlineMeeting ? { conferenceDataVersion: 1 } : {}),
+                requestBody: BuildGoogleEventBody(params.Changes, true)
+            });
+            return { Success: true, Event: ToCalendarEvent(response.data) };
+        });
+    }
+    /**
+     * Deletes the event with `sendUpdates: 'all'`: from the organizer's calendar that cancels it for
+     * everyone; from an attendee's it removes that copy only. Google has no cancellation comment, so
+     * `Comment` is not sent. An event already gone (404 or 410) counts as cancelled.
+     */
+    async CancelEvent(params, credentials) {
+        const failure = (message, err) => {
+            const status = this.httpStatus(err);
+            return status === 404 || status === 410 ? { Success: true } : { Success: false, ErrorMessage: message };
+        };
+        return this.calendarCall('CancelEvent', params.Target, credentials, failure, async (calendar, calendarId) => {
+            await calendar.events.delete({ calendarId, eventId: params.ExternalEventID, sendUpdates: 'all' });
+            return { Success: true };
+        });
+    }
+    /** Reads one event with each attendee's response. */
+    async GetEvent(params, credentials) {
+        return this.calendarCall('GetEvent', params.Target, credentials, (message) => ({ Success: false, ErrorMessage: message }), async (calendar, calendarId) => {
+            const response = await calendar.events.get({ calendarId, eventId: params.ExternalEventID });
+            return { Success: true, Event: ToCalendarEvent(response.data) };
+        });
+    }
+    /**
+     * Incremental sync through `events.list`. With no token, a full read of the window (open-ended when
+     * the window is not given); with one, only what changed. Recurring events are expanded
+     * (`singleEvents`), on every request, since Google wants the same parameters on the incremental
+     * reads as on the full one. Pages are followed until the `nextSyncToken`. An expired token is a
+     * 410 Gone: that comes back as `ResyncRequired`.
+     */
+    async SyncEvents(params, credentials) {
+        const failure = (message, err) => ({
+            Success: false,
+            Changes: [],
+            ErrorMessage: message,
+            ResyncRequired: !!params.SyncToken && this.httpStatus(err) === 410
+        });
+        return this.calendarCall('SyncEvents', params.Target, credentials, failure, async (calendar, calendarId) => {
+            const result = { Success: true, Changes: [] };
+            let pageToken;
+            for (let page = 0; page < GOOGLE_MAX_SYNC_PAGES; page++) {
+                const response = await calendar.events.list(this.syncListParams(calendarId, params, pageToken));
+                result.Changes.push(...(response.data.items ?? []).map(ToCalendarChange));
+                pageToken = response.data.nextPageToken ?? undefined;
+                if (!pageToken) {
+                    result.NextSyncToken = response.data.nextSyncToken ?? undefined;
+                    break;
+                }
+            }
+            return result.NextSyncToken ? result : failure('Google Calendar sync ended without a nextSyncToken; nothing was applied.');
+        });
+    }
+    /** The `events.list` parameters for one page. A sync token excludes the window, as Google requires. */
+    syncListParams(calendarId, params, pageToken) {
+        return {
+            calendarId,
+            singleEvents: true,
+            ...(params.SyncToken
+                ? { syncToken: params.SyncToken }
+                : {
+                    ...(params.WindowStart ? { timeMin: params.WindowStart.toISOString() } : {}),
+                    ...(params.WindowEnd ? { timeMax: params.WindowEnd.toISOString() } : {})
+                }),
+            ...(pageToken ? { pageToken } : {})
+        };
+    }
+    /**
+     * The shared shape of every calendar call: refuse a missing target before any I/O, build the
+     * calendar client from the account's OAuth2 client, and turn a thrown error into a result.
+     */
+    async calendarCall(operation, target, credentials, failure, work) {
+        const refusal = CalendarTargetError(operation, target);
+        if (refusal || !target)
+            return failure(refusal ?? `${operation} needs a Target.`);
+        try {
+            const cached = this.getGmailClient(this.resolveCredentials(credentials));
+            cached.calendar ??= googleApis.google.calendar({ version: 'v3', auth: cached.auth });
+            return await work(cached.calendar, target.CalendarID?.trim() || target.Identifier.trim());
+        }
+        catch (err) {
+            return failure(`Google Calendar ${operation} failed for ${target.Identifier}: ${err instanceof Error ? err.message : String(err)}`, err);
+        }
+    }
+    /** The HTTP status on a googleapis (Gaxios) error: `.code`, `.status` or `.response.status`. */
+    httpStatus(error) {
+        if (typeof error !== 'object' || error === null)
+            return undefined;
+        const err = error;
+        const status = Number(err.response?.status ?? err.status ?? err.code);
+        return Number.isFinite(status) ? status : undefined;
+    }
     // ========================================================================
     // PUSH-NOTIFICATION SUBSCRIPTIONS
     // Gmail is SUBSCRIPTION-MANAGED and HINT-mode. A mailbox `users.watch` registration