@engenty/wizards-runtime 0.0.0-stage → 0.7.5

package/apps/runtime/dist/engenty/connections-google/connectors/calendar.js

@@ -0,0 +1,381 @@
+import { defineConnector, } from "../../shims/connections-sdk.js";
+import { z } from "zod";
+import { connectorAction, GOOGLE_OAUTH2, googleFetch, googleJson, } from "../shared.js";
+const CALENDAR_API = "https://www.googleapis.com/calendar/v3";
+const SCOPE_READONLY = "https://www.googleapis.com/auth/calendar.readonly";
+const SCOPE_EVENTS = "https://www.googleapis.com/auth/calendar.events";
+const ALL_DAY_DATE = /^\d{4}-\d{2}-\d{2}$/;
+function eventTime(t) {
+    return t?.dateTime ?? t?.date ?? null;
+}
+function toEventSummary(e) {
+    return {
+        all_day: Boolean(e.start?.date),
+        end: eventTime(e.end),
+        etag: e.etag ?? null,
+        event_id: e.id,
+        html_link: e.htmlLink ?? null,
+        location: e.location ?? null,
+        private_properties: e.extendedProperties?.private ?? null,
+        start: eventTime(e.start),
+        status: e.status ?? null,
+        summary: e.summary ?? null,
+        // RFC3339 last-modified stamp; drives the pull-back conflict rule.
+        updated: e.updated ?? null,
+    };
+}
+/** Bounds the incremental-sync page walk so a huge changelog can't hang. */
+const MAX_SYNC_PAGES = 20;
+const privatePropertiesField = z
+    .record(z.string(), z.string())
+    .optional()
+    .describe("Private key/value metadata stored on the event (extendedProperties.private), not visible to attendees. Used to tag events created by an integration.");
+/**
+ * "2026-07-04" → { date } (all-day); a timestamp → { dateTime }. When
+ * `timeZone` is given, a zone-less local timestamp is resolved by Google in
+ * that IANA zone (DST-safe) instead of requiring an explicit offset.
+ */
+function toEventDateTime(value, timeZone) {
+    if (ALL_DAY_DATE.test(value)) {
+        return { date: value };
+    }
+    return timeZone ? { dateTime: value, timeZone } : { dateTime: value };
+}
+const timeZoneField = z
+    .string()
+    .optional()
+    .describe('IANA time zone (e.g. "Europe/Vienna") for timed start/end given without an offset. Optional when start/end already carry an offset.');
+const calendarIdField = z
+    .string()
+    .optional()
+    .describe('Calendar id (default "primary", the user\'s main calendar).');
+const startField = z
+    .string()
+    .describe('Event start: ISO 8601 timestamp with offset (e.g. "2026-07-04T10:00:00+02:00") or a plain date "YYYY-MM-DD" for an all-day event.');
+const endField = z
+    .string()
+    .describe('Event end: ISO 8601 timestamp, or a plain date "YYYY-MM-DD" (exclusive) for an all-day event.');
+const attendeesField = z
+    .array(z.string().describe("Attendee email address."))
+    .optional()
+    .describe("Optional list of attendee email addresses.");
+const sendUpdatesField = z
+    .enum(["all", "externalOnly", "none"])
+    .optional()
+    .describe('Whom Google e-mails about the change: "all" attendees, "externalOnly" (outside the organisation) or "none" (default).');
+/** `?sendUpdates=` for a write, when the caller asked Google to tell the attendees. */
+const updatesQuery = (value) => value ? `?sendUpdates=${encodeURIComponent(value)}` : "";
+export const calendarConnector = defineConnector({
+    actions: [
+        connectorAction({
+            description: "List the calendars the connected account can see, with id, name, primary flag and access role.",
+            group: "read",
+            handler: async (_input, ctx) => {
+                const data = await googleJson(ctx, `${CALENDAR_API}/users/me/calendarList?maxResults=100`);
+                return {
+                    calendars: (data.items ?? []).map((c) => ({
+                        access_role: c.accessRole ?? null,
+                        description: c.description ?? null,
+                        id: c.id,
+                        primary: Boolean(c.primary),
+                        summary: c.summary ?? null,
+                        time_zone: c.timeZone ?? null,
+                    })),
+                };
+            },
+            id: "list_calendars",
+            inputSchema: z.object({}),
+            providerScopes: [SCOPE_READONLY],
+            summary: "List Google calendars",
+        }),
+        connectorAction({
+            description: "List events from a calendar in a time window, ordered by start time (recurring events expanded to single instances). For incremental two-way sync, pass a prior `sync_token` to fetch only changes since then, or set `return_sync_token` to receive a `next_sync_token` for the next incremental pull.",
+            group: "read",
+            handler: async (input, ctx) => {
+                const calendarId = input.calendar_id ?? "primary";
+                const eventsUrl = `${CALENDAR_API}/calendars/${encodeURIComponent(calendarId)}/events`;
+                // Sync mode: a token was supplied, or the caller wants one back. Both
+                // require draining every page so the terminal nextSyncToken is captured
+                // (Google only returns it on the last page of a completed sync).
+                const syncMode = input.sync_token !== undefined || input.return_sync_token === true;
+                if (!syncMode) {
+                    const url = new URL(eventsUrl);
+                    url.searchParams.set("singleEvents", "true");
+                    url.searchParams.set("orderBy", "startTime");
+                    url.searchParams.set("maxResults", String(input.max_results ?? 10));
+                    if (input.time_min) {
+                        url.searchParams.set("timeMin", input.time_min);
+                    }
+                    if (input.time_max) {
+                        url.searchParams.set("timeMax", input.time_max);
+                    }
+                    const data = await googleJson(ctx, url.toString());
+                    return {
+                        calendar_id: calendarId,
+                        next_sync_token: null,
+                        sync_token_expired: false,
+                        events: (data.items ?? []).map((e) => ({
+                            ...toEventSummary(e),
+                            attendee_count: e.attendees?.length ?? 0,
+                        })),
+                    };
+                }
+                const items = [];
+                let pageToken;
+                let nextSyncToken = null;
+                for (let page = 0; page < MAX_SYNC_PAGES; page += 1) {
+                    const url = new URL(eventsUrl);
+                    // singleEvents must stay constant across a sync series; syncToken is
+                    // incompatible with orderBy/timeMin/timeMax (they only seed the
+                    // initial full sync when no token is present).
+                    url.searchParams.set("singleEvents", "true");
+                    url.searchParams.set("maxResults", String(input.max_results ?? 250));
+                    if (input.sync_token) {
+                        url.searchParams.set("syncToken", input.sync_token);
+                    }
+                    else {
+                        url.searchParams.set("orderBy", "startTime");
+                        if (input.time_min) {
+                            url.searchParams.set("timeMin", input.time_min);
+                        }
+                        if (input.time_max) {
+                            url.searchParams.set("timeMax", input.time_max);
+                        }
+                    }
+                    if (pageToken) {
+                        url.searchParams.set("pageToken", pageToken);
+                    }
+                    const res = await ctx.fetchImpl(url.toString(), {
+                        headers: { Authorization: `Bearer ${ctx.accessToken}` },
+                    });
+                    // 410 GONE ⇒ the sync token expired; the caller must re-list in full.
+                    if (res.status === 410) {
+                        return {
+                            calendar_id: calendarId,
+                            next_sync_token: null,
+                            sync_token_expired: true,
+                            events: [],
+                        };
+                    }
+                    if (!res.ok) {
+                        const body = (await res.text().catch(() => "")).slice(0, 200);
+                        throw new Error(`google_api_error (${res.status}): ${body}`);
+                    }
+                    const data = (await res.json());
+                    items.push(...(data.items ?? []));
+                    if (data.nextSyncToken) {
+                        nextSyncToken = data.nextSyncToken;
+                    }
+                    if (!data.nextPageToken) {
+                        break;
+                    }
+                    pageToken = data.nextPageToken;
+                }
+                return {
+                    calendar_id: calendarId,
+                    next_sync_token: nextSyncToken,
+                    sync_token_expired: false,
+                    events: items.map((e) => ({
+                        ...toEventSummary(e),
+                        attendee_count: e.attendees?.length ?? 0,
+                    })),
+                };
+            },
+            id: "list_events",
+            inputSchema: z.object({
+                calendar_id: calendarIdField,
+                max_results: z
+                    .number()
+                    .int()
+                    .min(1)
+                    .max(250)
+                    .optional()
+                    .describe("Maximum number of events to return (1-250, default 10)."),
+                return_sync_token: z
+                    .boolean()
+                    .optional()
+                    .describe("Drain all pages and return a `next_sync_token` to seed the next incremental pull (used for two-way sync)."),
+                sync_token: z
+                    .string()
+                    .optional()
+                    .describe("Incremental sync token from a prior `next_sync_token`. Returns only events changed since then (incompatible with time_min/time_max/order). If expired, the response sets `sync_token_expired`."),
+                time_max: z
+                    .string()
+                    .optional()
+                    .describe('Only events starting before this ISO 8601 timestamp (e.g. "2026-07-11T00:00:00Z").'),
+                time_min: z
+                    .string()
+                    .optional()
+                    .describe('Only events ending after this ISO 8601 timestamp (e.g. "2026-07-04T00:00:00Z").'),
+            }),
+            providerScopes: [SCOPE_READONLY],
+            summary: "List calendar events",
+        }),
+        connectorAction({
+            description: "Fetch one calendar event by id with full details: description, organizer, attendees and their response status.",
+            group: "read",
+            handler: async (input, ctx) => {
+                const calendarId = input.calendar_id ?? "primary";
+                const e = await googleJson(ctx, `${CALENDAR_API}/calendars/${encodeURIComponent(calendarId)}/events/${encodeURIComponent(input.event_id)}`);
+                return {
+                    ...toEventSummary(e),
+                    attendees: (e.attendees ?? []).map((a) => ({
+                        display_name: a.displayName ?? null,
+                        email: a.email ?? null,
+                        optional: Boolean(a.optional),
+                        response_status: a.responseStatus ?? null,
+                    })),
+                    calendar_id: calendarId,
+                    description: e.description ?? null,
+                    organizer: e.organizer?.email ?? null,
+                };
+            },
+            id: "get_event",
+            inputSchema: z.object({
+                calendar_id: calendarIdField,
+                event_id: z.string().describe("Calendar event id."),
+            }),
+            providerScopes: [SCOPE_READONLY],
+            summary: "Get a calendar event",
+        }),
+        connectorAction({
+            description: "Create a calendar event (timed or all-day), optionally inviting attendees by email.",
+            group: "write",
+            handler: async (input, ctx) => {
+                const calendarId = input.calendar_id ?? "primary";
+                const created = await googleJson(ctx, `${CALENDAR_API}/calendars/${encodeURIComponent(calendarId)}/events${updatesQuery(input.send_updates)}`, {
+                    body: JSON.stringify({
+                        end: toEventDateTime(input.end, input.time_zone),
+                        start: toEventDateTime(input.start, input.time_zone),
+                        summary: input.summary,
+                        ...(input.description ? { description: input.description } : {}),
+                        ...(input.location ? { location: input.location } : {}),
+                        ...(input.attendees?.length
+                            ? { attendees: input.attendees.map((email) => ({ email })) }
+                            : {}),
+                        ...(input.private_properties
+                            ? { extendedProperties: { private: input.private_properties } }
+                            : {}),
+                    }),
+                    headers: { "Content-Type": "application/json" },
+                    method: "POST",
+                });
+                return { ...toEventSummary(created), calendar_id: calendarId };
+            },
+            id: "create_event",
+            inputSchema: z.object({
+                attendees: attendeesField,
+                calendar_id: calendarIdField,
+                description: z
+                    .string()
+                    .optional()
+                    .describe("Optional event description/notes."),
+                end: endField,
+                location: z
+                    .string()
+                    .optional()
+                    .describe("Where the event takes place: an address, a phone number or a meeting link."),
+                private_properties: privatePropertiesField,
+                send_updates: sendUpdatesField,
+                start: startField,
+                summary: z.string().describe("Event title."),
+                time_zone: timeZoneField,
+            }),
+            providerScopes: [SCOPE_EVENTS],
+            summary: "Create a calendar event",
+        }),
+        connectorAction({
+            description: "Update fields of an existing calendar event (patch semantics: only the provided fields change).",
+            group: "write",
+            handler: async (input, ctx) => {
+                const calendarId = input.calendar_id ?? "primary";
+                const patch = {};
+                if (input.summary !== undefined) {
+                    patch.summary = input.summary;
+                }
+                if (input.description !== undefined) {
+                    patch.description = input.description;
+                }
+                if (input.location !== undefined) {
+                    patch.location = input.location;
+                }
+                if (input.start !== undefined) {
+                    patch.start = toEventDateTime(input.start, input.time_zone);
+                }
+                if (input.end !== undefined) {
+                    patch.end = toEventDateTime(input.end, input.time_zone);
+                }
+                if (input.attendees !== undefined) {
+                    patch.attendees = input.attendees.map((email) => ({ email }));
+                }
+                if (input.private_properties !== undefined) {
+                    patch.extendedProperties = { private: input.private_properties };
+                }
+                const updated = await googleJson(ctx, `${CALENDAR_API}/calendars/${encodeURIComponent(calendarId)}/events/${encodeURIComponent(input.event_id)}${updatesQuery(input.send_updates)}`, {
+                    body: JSON.stringify(patch),
+                    headers: { "Content-Type": "application/json" },
+                    method: "PATCH",
+                });
+                return { ...toEventSummary(updated), calendar_id: calendarId };
+            },
+            id: "update_event",
+            inputSchema: z
+                .object({
+                attendees: attendeesField,
+                calendar_id: calendarIdField,
+                description: z
+                    .string()
+                    .optional()
+                    .describe("New event description (replaces the existing one)."),
+                end: endField.optional(),
+                event_id: z.string().describe("Calendar event id to update."),
+                location: z
+                    .string()
+                    .optional()
+                    .describe("New location (replaces the existing one)."),
+                private_properties: privatePropertiesField,
+                send_updates: sendUpdatesField,
+                start: startField.optional(),
+                summary: z.string().optional().describe("New event title."),
+                time_zone: timeZoneField,
+            })
+                .refine((v) => v.attendees !== undefined ||
+                v.description !== undefined ||
+                v.end !== undefined ||
+                v.location !== undefined ||
+                v.private_properties !== undefined ||
+                v.start !== undefined ||
+                v.summary !== undefined, { message: "Provide at least one field to update." }),
+            providerScopes: [SCOPE_EVENTS],
+            summary: "Update a calendar event",
+        }),
+        connectorAction({
+            description: "Delete a calendar event permanently (attendees are notified of the cancellation).",
+            group: "destructive",
+            handler: async (input, ctx) => {
+                const calendarId = input.calendar_id ?? "primary";
+                await googleFetch(ctx, `${CALENDAR_API}/calendars/${encodeURIComponent(calendarId)}/events/${encodeURIComponent(input.event_id)}${updatesQuery(input.send_updates)}`, { method: "DELETE" });
+                return {
+                    calendar_id: calendarId,
+                    deleted: true,
+                    event_id: input.event_id,
+                };
+            },
+            id: "delete_event",
+            inputSchema: z.object({
+                calendar_id: calendarIdField,
+                event_id: z.string().describe("Calendar event id to delete."),
+                send_updates: sendUpdatesField,
+            }),
+            providerScopes: [SCOPE_EVENTS],
+            summary: "Delete a calendar event",
+        }),
+    ],
+    auth: { kind: "oauth2", oauth2: GOOGLE_OAUTH2 },
+    description: "Read and manage events in a connected Google Calendar account.",
+    icon: "logo:google-calendar",
+    id: "google-calendar",
+    moduleId: "connections-google",
+    name: "Google Calendar",
+    toolPrefix: "gcal",
+});

package/apps/runtime/dist/engenty/connections-google/connectors/contacts.js

@@ -0,0 +1,94 @@
+import { defineConnector, } from "../../shims/connections-sdk.js";
+import { z } from "zod";
+import { connectorAction, GOOGLE_OAUTH2, googleJson } from "../shared.js";
+const PEOPLE_API = "https://people.googleapis.com/v1";
+const SCOPE_READONLY = "https://www.googleapis.com/auth/contacts.readonly";
+function mapPerson(person) {
+    const name = person.names?.[0];
+    const org = person.organizations?.[0];
+    return {
+        display_name: name?.displayName ?? null,
+        email: person.emailAddresses?.[0]?.value ?? null,
+        family_name: name?.familyName ?? null,
+        given_name: name?.givenName ?? null,
+        organization: org?.name ?? null,
+        phone: person.phoneNumbers?.[0]?.value ?? null,
+        resource_name: person.resourceName ?? null,
+        title: org?.title ?? null,
+    };
+}
+export const contactsConnector = defineConnector({
+    actions: [
+        connectorAction({
+            description: "List contacts from Google Contacts (People API). Returns compact rows suitable for import: display name, given/family name, email, phone, organization, title.",
+            group: "read",
+            handler: async (input, ctx) => {
+                const url = new URL(`${PEOPLE_API}/people/me/connections`);
+                url.searchParams.set("personFields", "names,emailAddresses,phoneNumbers,organizations");
+                url.searchParams.set("pageSize", String(input.page_size ?? 100));
+                if (input.page_token) {
+                    url.searchParams.set("pageToken", input.page_token);
+                }
+                const data = await googleJson(ctx, url.toString());
+                return {
+                    contacts: (data.connections ?? []).map(mapPerson),
+                    next_page_token: data.nextPageToken ?? null,
+                    total_people: data.totalPeople ?? null,
+                };
+            },
+            id: "list_contacts",
+            inputSchema: z.object({
+                page_size: z
+                    .number()
+                    .int()
+                    .min(1)
+                    .max(1000)
+                    .optional()
+                    .describe("Page size (1–1000). Defaults to 100."),
+                page_token: z
+                    .string()
+                    .optional()
+                    .describe("Pagination token from a previous list_contacts call."),
+            }),
+            providerScopes: [SCOPE_READONLY],
+            summary: "List Google Contacts",
+        }),
+        connectorAction({
+            description: "Search Google Contacts by a query string (name, email, phone). Returns the same compact contact rows as list_contacts.",
+            group: "read",
+            handler: async (input, ctx) => {
+                const url = new URL(`${PEOPLE_API}/people:searchContacts`);
+                url.searchParams.set("query", input.query);
+                url.searchParams.set("readMask", "names,emailAddresses,phoneNumbers,organizations");
+                url.searchParams.set("pageSize", String(input.page_size ?? 30));
+                const data = await googleJson(ctx, url.toString());
+                return {
+                    contacts: (data.results ?? [])
+                        .map((r) => r.person)
+                        .filter((p) => Boolean(p))
+                        .map(mapPerson),
+                };
+            },
+            id: "search_contacts",
+            inputSchema: z.object({
+                page_size: z
+                    .number()
+                    .int()
+                    .min(1)
+                    .max(30)
+                    .optional()
+                    .describe("Max results (1–30). Defaults to 30."),
+                query: z.string().min(1).describe("Search query."),
+            }),
+            providerScopes: [SCOPE_READONLY],
+            summary: "Search Google Contacts",
+        }),
+    ],
+    auth: { kind: "oauth2", oauth2: GOOGLE_OAUTH2 },
+    description: "Import and search people from Google Contacts via the People API.",
+    icon: "logo:gmail",
+    id: "google-contacts",
+    moduleId: "connections-google",
+    name: "Google Contacts",
+    toolPrefix: "gcontacts",
+});