@automate.ax/integration-contracts 0.55.0

package/src/google-calendar/google-calendar.ts

@@ -0,0 +1,727 @@
+import { Buffer } from "node:buffer"
+import { auth, calendar, type calendar_v3 } from "@googleapis/calendar"
+import { z } from "zod"
+import {
+  ACL_PAGE_SCHEMA,
+  ACL_RULE_SCHEMA,
+  CALENDAR_EVENT_SCHEMA,
+  CALENDAR_PAGE_SCHEMA,
+  CALENDAR_SCHEMA,
+  COLOR_PALETTE_SCHEMA,
+  EVENT_PAGE_SCHEMA,
+  EVENT_DETAILS_INPUT_SCHEMA,
+  EVENT_SCHEDULE_INPUT_SCHEMA,
+  FREE_BUSY_SCHEMA,
+} from "./schemas"
+
+const GOOGLE_CALENDAR_HOSTS = new Set(["calendar.google.com", "www.google.com"])
+const GOOGLE_CALENDAR_SECRET_SCHEMA = z.object({
+  accessToken: z.string().min(1),
+})
+
+/**
+ * Creates the official Calendar client from a resolved Google integration
+ * secret.
+ *
+ * @param secret - Refreshed Google integration secret.
+ */
+export function getGoogleCalendarApi(secret: Record<string, unknown>) {
+  const { accessToken } = GOOGLE_CALENDAR_SECRET_SCHEMA.parse(secret)
+  return calendar({
+    auth: new auth.OAuth2({
+      credentials: { access_token: accessToken },
+    }),
+    version: "v3",
+  })
+}
+
+/**
+ * Resolves an exact calendar title or ID to the provider's canonical ID.
+ *
+ * Unknown references are returned unchanged so email-address and otherwise
+ * unlisted calendar IDs remain usable.
+ *
+ * @param calendarApi - Authenticated Google Calendar client.
+ * @param reference - Calendar title or ID, defaulting to `primary`.
+ */
+export async function resolveCalendarId(
+  calendarApi: calendar_v3.Calendar,
+  reference?: string,
+) {
+  return (await resolveCalendarIds(calendarApi, [reference]))[0]!
+}
+
+/**
+ * Resolves multiple exact calendar titles or IDs with one paginated listing.
+ *
+ * Unknown references are returned unchanged so email-address and otherwise
+ * unlisted calendar IDs remain usable.
+ *
+ * @param calendarApi - Authenticated Google Calendar client.
+ * @param references - Calendar titles or IDs, with absent values as primary.
+ */
+export async function resolveCalendarIds(
+  calendarApi: calendar_v3.Calendar,
+  references: (string | undefined)[],
+) {
+  if (references.every((value) => value === undefined || value === "primary")) {
+    return references.map(() => "primary")
+  }
+
+  const calendars: calendar_v3.Schema$CalendarListEntry[] = []
+  let pageToken: string | undefined
+  do {
+    const { data } = await calendarApi.calendarList.list({
+      maxResults: 250,
+      pageToken,
+      showDeleted: false,
+      showHidden: true,
+    })
+    calendars.push(...(data.items ?? []))
+    pageToken = data.nextPageToken ?? undefined
+  } while (pageToken)
+
+  return references.map((reference) =>
+    resolveCalendarReference(calendars, reference),
+  )
+}
+
+/**
+ * Resolves one calendar reference against an already fetched calendar list.
+ *
+ * @param calendars - Visible Google Calendar list entries.
+ * @param reference - Calendar title or ID, defaulting to primary.
+ * @throws When the calendar title matches more than one visible calendar.
+ */
+export function resolveCalendarReference(
+  calendars: calendar_v3.Schema$CalendarListEntry[],
+  reference?: string,
+) {
+  if (reference === undefined || reference === "primary") return "primary"
+
+  const idMatch = calendars.find(({ id }) => id === reference)
+  if (idMatch?.id) return idMatch.id
+
+  const normalizedReference = reference.trim().toLowerCase()
+  const nameMatches = calendars.filter(
+    ({ summary, summaryOverride }) =>
+      summary?.trim().toLowerCase() === normalizedReference ||
+      summaryOverride?.trim().toLowerCase() === normalizedReference,
+  )
+  if (nameMatches.length === 1 && nameMatches[0]!.id) {
+    return nameMatches[0]!.id
+  }
+  if (nameMatches.length > 1) {
+    throw new Error(
+      `Google Calendar "${reference}" is ambiguous; matching IDs: ${nameMatches.map(({ id }) => id).join(", ")}.`,
+    )
+  }
+  return reference
+}
+
+/**
+ * Accepts a raw event ID or a standard Google Calendar event URL.
+ *
+ * @param event - Event ID or URL.
+ * @throws When a URL is not a recognizable Google Calendar event URL.
+ */
+export function normalizeEventId(event: string) {
+  const value = event.trim()
+  if (!URL.canParse(value)) return value
+
+  const url = new URL(value)
+  if (!GOOGLE_CALENDAR_HOSTS.has(url.hostname)) {
+    throw new Error(`Expected a Google Calendar URL, received "${value}".`)
+  }
+  const encodedEvent = url.searchParams.get("eid")
+  if (!encodedEvent) {
+    throw new Error(`Could not find an event ID in "${value}".`)
+  }
+  const [eventId] = Buffer.from(encodedEvent, "base64url")
+    .toString("utf8")
+    .split(" ")
+  if (!eventId) {
+    throw new Error(`Could not decode the event ID in "${value}".`)
+  }
+  return eventId
+}
+
+/**
+ * Converts an ergonomic timed or all-day schedule to Calendar API date-times.
+ *
+ * @param schedule - Timed or all-day event schedule.
+ */
+export function toEventDateTimes(
+  schedule: z.infer<typeof EVENT_SCHEDULE_INPUT_SCHEMA>,
+) {
+  if ("startDate" in schedule) {
+    return {
+      end: {
+        date: schedule.endDate ?? addDays(schedule.startDate, 1),
+      },
+      start: { date: schedule.startDate },
+    }
+  }
+  return {
+    end: { dateTime: schedule.end, timeZone: schedule.timeZone },
+    start: { dateTime: schedule.start, timeZone: schedule.timeZone },
+  }
+}
+
+/**
+ * Normalizes a provider event into the stable public Calendar event shape.
+ *
+ * @param event - Provider event.
+ * @param calendarId - Calendar from which the event was read.
+ * @throws When the provider omits the event ID.
+ */
+export function normalizeCalendarEvent(
+  event: calendar_v3.Schema$Event,
+  calendarId: string,
+): z.infer<typeof CALENDAR_EVENT_SCHEMA> {
+  if (!event.id) {
+    throw new Error("Google Calendar returned an event without an ID.")
+  }
+  return {
+    attachments: (event.attachments ?? []).flatMap((attachment) =>
+      attachment.fileUrl
+        ? [
+            {
+              fileId: attachment.fileId ?? undefined,
+              fileUrl: attachment.fileUrl,
+              iconLink: attachment.iconLink ?? undefined,
+              mimeType: attachment.mimeType ?? undefined,
+              title: attachment.title ?? undefined,
+            },
+          ]
+        : [],
+    ),
+    attendees: (event.attendees ?? []).flatMap((attendee) =>
+      attendee.email
+        ? [
+            {
+              additionalGuests: attendee.additionalGuests ?? undefined,
+              comment: attendee.comment ?? undefined,
+              displayName: attendee.displayName ?? undefined,
+              email: attendee.email,
+              optional: attendee.optional ?? undefined,
+              organizer: attendee.organizer ?? false,
+              resource: attendee.resource ?? undefined,
+              responseStatus: normalizeResponseStatus(attendee.responseStatus),
+              self: attendee.self ?? false,
+            },
+          ]
+        : [],
+    ),
+    calendarId,
+    colorId: event.colorId ?? undefined,
+    conference: normalizeConference(event.conferenceData),
+    createdAt: event.created ?? undefined,
+    creator: normalizePrincipal(event.creator),
+    description: event.description ?? undefined,
+    end: event.end ? normalizeEventTime(event.end) : undefined,
+    extendedProperties: {
+      private: withoutNullValues(event.extendedProperties?.private),
+      shared: withoutNullValues(event.extendedProperties?.shared),
+    },
+    guestsCanInviteOthers: event.guestsCanInviteOthers ?? true,
+    guestsCanModify: event.guestsCanModify ?? false,
+    guestsCanSeeOtherGuests: event.guestsCanSeeOtherGuests ?? true,
+    hangoutLink: event.hangoutLink ?? undefined,
+    htmlLink: event.htmlLink ?? undefined,
+    id: event.id,
+    iCalUID: event.iCalUID ?? undefined,
+    location: event.location ?? undefined,
+    originalStart: event.originalStartTime
+      ? normalizeEventTime(event.originalStartTime)
+      : undefined,
+    organizer: normalizePrincipal(event.organizer),
+    recurrence: event.recurrence ?? [],
+    recurringEventId: event.recurringEventId ?? undefined,
+    reminders: {
+      overrides: (event.reminders?.overrides ?? []).flatMap((reminder) =>
+        reminder.method && reminder.minutes != null
+          ? [
+              {
+                method: normalizeReminderMethod(reminder.method),
+                minutes: reminder.minutes,
+              },
+            ]
+          : [],
+      ),
+      useDefault: event.reminders?.useDefault ?? true,
+    },
+    sequence: event.sequence ?? 0,
+    start: event.start ? normalizeEventTime(event.start) : undefined,
+    status: normalizeEventStatus(event.status),
+    summary: event.summary ?? "",
+    transparency:
+      event.transparency === "transparent" ? "transparent" : "opaque",
+    type: event.eventType ?? "default",
+    updatedAt: event.updated ?? undefined,
+    visibility: normalizeVisibility(event.visibility),
+  }
+}
+
+/**
+ * Normalizes a provider event page while retaining pagination and sync tokens.
+ *
+ * @param events - Provider event collection.
+ * @param calendarId - Calendar from which events were read.
+ */
+export function normalizeEventPage(
+  events: calendar_v3.Schema$Events,
+  calendarId: string,
+): z.infer<typeof EVENT_PAGE_SCHEMA> {
+  return {
+    events: (events.items ?? []).map((event) =>
+      normalizeCalendarEvent(event, calendarId),
+    ),
+    nextPageToken: events.nextPageToken ?? undefined,
+    nextSyncToken: events.nextSyncToken ?? undefined,
+    timeZone: events.timeZone ?? undefined,
+    updatedAt: events.updated ?? undefined,
+  }
+}
+
+/**
+ * Normalizes a calendar or calendar-list entry.
+ *
+ * @param value - Provider calendar metadata.
+ * @param id - Calendar ID when not included in the provider resource.
+ * @throws When neither the resource nor caller supplies a calendar ID.
+ */
+export function normalizeCalendar(
+  value: calendar_v3.Schema$Calendar | calendar_v3.Schema$CalendarListEntry,
+  id?: string,
+): z.infer<typeof CALENDAR_SCHEMA> {
+  const calendarId = value.id ?? id
+  if (!calendarId) {
+    throw new Error("Google Calendar returned calendar metadata without an ID.")
+  }
+  const listEntry = "accessRole" in value ? value : undefined
+  return {
+    accessRole: listEntry?.accessRole ?? undefined,
+    autoAcceptInvitations: value.autoAcceptInvitations ?? false,
+    backgroundColor: listEntry?.backgroundColor ?? undefined,
+    colorId: listEntry?.colorId ?? undefined,
+    conferenceSolutionTypes:
+      value.conferenceProperties?.allowedConferenceSolutionTypes ?? [],
+    defaultReminders:
+      listEntry?.defaultReminders?.flatMap((reminder) =>
+        reminder.method && reminder.minutes != null
+          ? [{ method: reminder.method, minutes: reminder.minutes }]
+          : [],
+      ) ?? [],
+    dataOwner: value.dataOwner ?? undefined,
+    deleted: listEntry?.deleted ?? false,
+    description: value.description ?? undefined,
+    foregroundColor: listEntry?.foregroundColor ?? undefined,
+    hidden: listEntry?.hidden ?? false,
+    id: calendarId,
+    location: value.location ?? undefined,
+    notifications:
+      listEntry?.notificationSettings?.notifications?.flatMap((notification) =>
+        notification.type &&
+        (notification.type === "eventCreation" ||
+          notification.type === "eventChange" ||
+          notification.type === "eventCancellation" ||
+          notification.type === "eventResponse" ||
+          notification.type === "agenda")
+          ? [{ type: notification.type }]
+          : [],
+      ) ?? [],
+    primary: listEntry?.primary ?? id === "primary",
+    selected: listEntry?.selected ?? false,
+    summary: value.summary ?? "",
+    summaryOverride: listEntry?.summaryOverride ?? undefined,
+    timeZone: value.timeZone ?? undefined,
+  }
+}
+
+/**
+ * Normalizes a provider calendar-list page.
+ *
+ * @param value - Provider calendar-list collection.
+ */
+export function normalizeCalendarPage(
+  value: calendar_v3.Schema$CalendarList,
+): z.infer<typeof CALENDAR_PAGE_SCHEMA> {
+  return {
+    calendars: (value.items ?? []).map((entry) => normalizeCalendar(entry)),
+    nextPageToken: value.nextPageToken ?? undefined,
+    nextSyncToken: value.nextSyncToken ?? undefined,
+  }
+}
+
+/**
+ * Normalizes a provider free/busy response.
+ *
+ * @param value - Provider free/busy response.
+ * @throws When the provider omits the requested time range.
+ */
+export function normalizeFreeBusy(
+  value: calendar_v3.Schema$FreeBusyResponse,
+): z.infer<typeof FREE_BUSY_SCHEMA> {
+  if (!value.timeMin || !value.timeMax) {
+    throw new Error("Google Calendar returned an incomplete free/busy range.")
+  }
+  return {
+    calendars: Object.entries(value.calendars ?? {}).map(
+      ([calendarId, result]) => ({
+        busy: (result.busy ?? []).flatMap((period) =>
+          period.start && period.end
+            ? [{ end: period.end, start: period.start }]
+            : [],
+        ),
+        calendarId,
+        errors: (result.errors ?? []).map((error) => ({
+          domain: error.domain ?? undefined,
+          reason: error.reason ?? undefined,
+        })),
+      }),
+    ),
+    timeMax: value.timeMax,
+    timeMin: value.timeMin,
+  }
+}
+
+/**
+ * Normalizes Google Calendar color definitions.
+ *
+ * @param value - Provider color palette.
+ */
+export function normalizeColors(
+  value: calendar_v3.Schema$Colors,
+): z.infer<typeof COLOR_PALETTE_SCHEMA> {
+  return {
+    calendars: normalizeColorDefinitions(value.calendar),
+    events: normalizeColorDefinitions(value.event),
+    updatedAt: value.updated ?? undefined,
+  }
+}
+
+/**
+ * Normalizes one calendar ACL rule.
+ *
+ * @param value - Provider ACL rule.
+ * @throws When the provider omits the rule ID or scope.
+ */
+export function normalizeAclRule(
+  value: calendar_v3.Schema$AclRule,
+): z.infer<typeof ACL_RULE_SCHEMA> {
+  if (!value.id || !value.scope?.type) {
+    throw new Error("Google Calendar returned an incomplete ACL rule.")
+  }
+  return {
+    id: value.id,
+    role: normalizeAclRole(value.role),
+    scope: {
+      type: normalizeAclScope(value.scope.type),
+      value: value.scope.value ?? undefined,
+    },
+  }
+}
+
+/**
+ * Normalizes a page of calendar ACL rules.
+ *
+ * @param value - Provider ACL collection.
+ */
+export function normalizeAclPage(
+  value: calendar_v3.Schema$Acl,
+): z.infer<typeof ACL_PAGE_SCHEMA> {
+  return {
+    nextPageToken: value.nextPageToken ?? undefined,
+    nextSyncToken: value.nextSyncToken ?? undefined,
+    rules: (value.items ?? []).map(normalizeAclRule),
+  }
+}
+
+/**
+ * Finds common free windows of a requested duration.
+ *
+ * @param freeBusy - Normalized free/busy response.
+ * @param durationMinutes - Required duration.
+ * @param stepMinutes - Candidate-start increment.
+ * @param limit - Maximum returned slots.
+ */
+export function findAvailableSlots(
+  freeBusy: z.infer<typeof FREE_BUSY_SCHEMA>,
+  durationMinutes: number,
+  stepMinutes: number,
+  limit: number,
+) {
+  const queryEnd = new Date(freeBusy.timeMax).getTime()
+  const duration = durationMinutes * 60_000
+  const step = stepMinutes * 60_000
+  const busy = mergePeriods(
+    freeBusy.calendars.flatMap(({ busy: periods }) =>
+      periods.map(({ end, start }) => ({
+        end: new Date(end).getTime(),
+        start: new Date(start).getTime(),
+      })),
+    ),
+  )
+  const slots: { durationMinutes: number; end: string; start: string }[] = []
+
+  for (
+    let candidate = new Date(freeBusy.timeMin).getTime();
+    candidate + duration <= queryEnd && slots.length < limit;
+    candidate += step
+  ) {
+    const candidateEnd = candidate + duration
+    if (
+      !busy.some(
+        (period) => candidate < period.end && candidateEnd > period.start,
+      )
+    ) {
+      slots.push({
+        durationMinutes,
+        end: new Date(candidateEnd).toISOString(),
+        start: new Date(candidate).toISOString(),
+      })
+    }
+  }
+  return slots
+}
+
+/**
+ * Builds the provider event body shared by create, update, and import actions.
+ *
+ * @param input - Public event fields.
+ */
+export function toEventResource(
+  input: z.infer<typeof EVENT_DETAILS_INPUT_SCHEMA>,
+): calendar_v3.Schema$Event {
+  return {
+    attachments: input.attachments,
+    attendees: input.attendees,
+    colorId: input.colorId,
+    description: input.description,
+    ...(input.schedule ? toEventDateTimes(input.schedule) : {}),
+    extendedProperties: input.extendedProperties,
+    guestsCanInviteOthers: input.guestsCanInviteOthers,
+    guestsCanModify: input.guestsCanModify,
+    guestsCanSeeOtherGuests: input.guestsCanSeeOtherGuests,
+    location: input.location,
+    recurrence: input.recurrence,
+    reminders: input.reminders,
+    summary: input.summary,
+    transparency: input.transparency,
+    visibility: input.visibility,
+  }
+}
+
+/**
+ * Adds whole UTC days to an ISO calendar date.
+ *
+ * @param date - ISO calendar date.
+ * @param days - Number of days to add.
+ */
+function addDays(date: string, days: number) {
+  const value = new Date(`${date}T00:00:00.000Z`)
+  value.setUTCDate(value.getUTCDate() + days)
+  return value.toISOString().slice(0, 10)
+}
+
+/**
+ * Normalizes an all-day or timed provider event boundary.
+ *
+ * @param value - Provider event date-time.
+ */
+function normalizeEventTime(value: calendar_v3.Schema$EventDateTime) {
+  return {
+    date: value.date ?? undefined,
+    dateTime: value.dateTime ?? undefined,
+    timeZone: value.timeZone ?? undefined,
+  }
+}
+
+/**
+ * Normalizes an event creator or organizer.
+ *
+ * @param value - Provider event principal.
+ */
+function normalizePrincipal(value: calendar_v3.Schema$Event["creator"]) {
+  return value
+    ? {
+        displayName: value.displayName ?? undefined,
+        email: value.email ?? undefined,
+        self: value.self ?? false,
+      }
+    : undefined
+}
+
+/**
+ * Normalizes event conference entry points and creation state.
+ *
+ * @param value - Provider conference data.
+ */
+function normalizeConference(
+  value: calendar_v3.Schema$ConferenceData | null | undefined,
+) {
+  if (!value) return undefined
+  return {
+    conferenceId: value.conferenceId ?? undefined,
+    creationStatus: normalizeConferenceStatus(
+      value.createRequest?.status?.statusCode,
+    ),
+    entryPoints: (value.entryPoints ?? []).flatMap((entryPoint) =>
+      entryPoint.entryPointType && entryPoint.uri
+        ? [
+            {
+              label: entryPoint.label ?? undefined,
+              passcode:
+                entryPoint.passcode ??
+                entryPoint.password ??
+                entryPoint.pin ??
+                undefined,
+              type: entryPoint.entryPointType,
+              uri: entryPoint.uri,
+            },
+          ]
+        : [],
+    ),
+    name: value.conferenceSolution?.name ?? undefined,
+  }
+}
+
+/**
+ * Narrows a provider conference creation status.
+ *
+ * @param value - Provider status.
+ */
+function normalizeConferenceStatus(
+  value: string | null | undefined,
+): "pending" | "success" | "failure" | undefined {
+  return value === "pending" || value === "success" || value === "failure"
+    ? value
+    : undefined
+}
+
+/**
+ * Narrows an attendee response status.
+ *
+ * @param value - Provider response status.
+ */
+function normalizeResponseStatus(value: string | null | undefined) {
+  return value === "declined" || value === "tentative" || value === "accepted"
+    ? value
+    : "needsAction"
+}
+
+/**
+ * Narrows a reminder delivery method.
+ *
+ * @param value - Provider reminder method.
+ */
+function normalizeReminderMethod(value: string) {
+  return value === "email" ? "email" : "popup"
+}
+
+/**
+ * Narrows an event lifecycle status.
+ *
+ * @param value - Provider event status.
+ */
+function normalizeEventStatus(value: string | null | undefined) {
+  return value === "tentative" || value === "cancelled" ? value : "confirmed"
+}
+
+/**
+ * Narrows an event visibility.
+ *
+ * @param value - Provider visibility.
+ */
+function normalizeVisibility(value: string | null | undefined) {
+  return value === "public" || value === "private" || value === "confidential"
+    ? value
+    : "default"
+}
+
+/**
+ * Narrows an ACL permission role.
+ *
+ * @param value - Provider ACL role.
+ */
+function normalizeAclRole(value: string | null | undefined) {
+  return value === "none" ||
+    value === "freeBusyReader" ||
+    value === "reader" ||
+    value === "writer"
+    ? value
+    : "owner"
+}
+
+/**
+ * Narrows an ACL scope type.
+ *
+ * @param value - Provider ACL scope type.
+ */
+function normalizeAclScope(value: string) {
+  return value === "default" || value === "group" || value === "domain"
+    ? value
+    : "user"
+}
+
+/**
+ * Removes null values from a provider string record.
+ *
+ * @param value - Nullable provider record.
+ */
+function withoutNullValues(
+  value: Record<string, string | null> | null | undefined,
+) {
+  return Object.fromEntries(
+    Object.entries(value ?? {}).flatMap(([key, item]) =>
+      item === null ? [] : [[key, item]],
+    ),
+  )
+}
+
+/**
+ * Normalizes complete color definitions keyed by provider ID.
+ *
+ * @param definitions - Provider color definitions.
+ */
+function normalizeColorDefinitions(
+  definitions:
+    | Record<string, calendar_v3.Schema$ColorDefinition>
+    | null
+    | undefined,
+) {
+  return Object.fromEntries(
+    Object.entries(definitions ?? {}).flatMap(([id, definition]) =>
+      definition.background && definition.foreground
+        ? [
+            [
+              id,
+              {
+                background: definition.background,
+                foreground: definition.foreground,
+              },
+            ],
+          ]
+        : [],
+    ),
+  )
+}
+
+/**
+ * Merges overlapping numeric time periods.
+ *
+ * @param periods - Busy periods expressed as epoch milliseconds.
+ */
+function mergePeriods(periods: { end: number; start: number }[]) {
+  return periods
+    .toSorted((left, right) => left.start - right.start)
+    .reduce<{ end: number; start: number }[]>((merged, period) => {
+      const previous = merged.at(-1)
+      if (!previous || period.start > previous.end) return [...merged, period]
+      return [
+        ...merged.slice(0, -1),
+        { end: Math.max(previous.end, period.end), start: previous.start },
+      ]
+    }, [])
+}