wizards 0.1.9

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

@@ -0,0 +1,567 @@
+import { defineConnector, } from "../../shims/connections-sdk.js";
+import { z } from "zod";
+import { connectorAction, GOOGLE_OAUTH2, googleJson } from "../shared.js";
+const GMAIL_API = "https://gmail.googleapis.com/gmail/v1/users/me";
+const SCOPE_READONLY = "https://www.googleapis.com/auth/gmail.readonly";
+const SCOPE_COMPOSE = "https://www.googleapis.com/auth/gmail.compose";
+const SCOPE_MODIFY = "https://www.googleapis.com/auth/gmail.modify";
+const SCOPE_SEND = "https://www.googleapis.com/auth/gmail.send";
+function getHeader(headers, name) {
+    return headers?.find((h) => h.name.toLowerCase() === name.toLowerCase())
+        ?.value;
+}
+function parseEmailAddress(raw) {
+    // "John Doe <john@example.com>" → { name: "John Doe", email: "john@example.com" }
+    const match = raw.match(/^(.+?)\s*<([^>]+)>$/);
+    if (match) {
+        return { email: match[2], name: match[1].trim().replace(/^"|"$/g, "") };
+    }
+    return { email: raw.trim() };
+}
+function parseAddressList(raw) {
+    if (!raw) {
+        return [];
+    }
+    return raw
+        .split(",")
+        .map((a) => parseEmailAddress(a.trim()).email)
+        .filter((e) => e.length > 0);
+}
+/** To is often empty for mailing lists / Google Groups; Delivered-To has the mailbox. */
+function parseRecipientEmails(headers) {
+    const to = parseAddressList(getHeader(headers, "To"));
+    if (to.length > 0) {
+        return to;
+    }
+    const delivered = parseAddressList(getHeader(headers, "Delivered-To"));
+    if (delivered.length > 0) {
+        return delivered;
+    }
+    return parseAddressList(getHeader(headers, "X-Original-To"));
+}
+/** Gmail uses URL-safe base64 for message bodies. */
+function decodeBase64Url(data) {
+    const base64 = data.replace(/-/g, "+").replace(/_/g, "/");
+    return Buffer.from(base64, "base64").toString("utf-8");
+}
+/** Gmail attachment API returns URL-safe base64 without padding. */
+export function gmailAttachmentDataToBase64(data) {
+    const base64 = data.replace(/-/g, "+").replace(/_/g, "/");
+    const pad = base64.length % 4;
+    return pad > 0 ? base64 + "=".repeat(4 - pad) : base64;
+}
+function extractBody(payload, mimeType) {
+    if (!payload) {
+        return null;
+    }
+    if (payload.mimeType === mimeType && payload.body?.data) {
+        return decodeBase64Url(payload.body.data);
+    }
+    if (payload.parts) {
+        for (const part of payload.parts) {
+            const result = extractBody(part, mimeType);
+            if (result) {
+                return result;
+            }
+        }
+    }
+    return null;
+}
+function parseGmailMessage(raw) {
+    const headers = raw.payload?.headers;
+    const { email: fromEmail, name: fromName } = parseEmailAddress(getHeader(headers, "From") ?? "");
+    return {
+        body_text: extractBody(raw.payload, "text/plain") ?? raw.snippet ?? null,
+        cc: parseAddressList(getHeader(headers, "Cc")),
+        date: raw.internalDate
+            ? new Date(Number(raw.internalDate)).toISOString()
+            : (getHeader(headers, "Date") ?? null),
+        from_email: fromEmail || null,
+        from_name: fromName ?? null,
+        message_id: raw.id,
+        subject: getHeader(headers, "Subject") ?? null,
+        to: parseRecipientEmails(headers),
+    };
+}
+// ─── Inbound message stream (module consumption API only) ───
+function collectAttachments(payload, out) {
+    if (!payload) {
+        return;
+    }
+    if (payload.filename && payload.body?.attachmentId) {
+        out.push({
+            attachment_id: payload.body.attachmentId,
+            content_id: getHeader(payload.headers, "Content-ID") ?? null,
+            filename: payload.filename,
+            mime_type: payload.mimeType ?? null,
+            size: payload.body.size ?? null,
+        });
+    }
+    for (const part of payload.parts ?? []) {
+        collectAttachments(part, out);
+    }
+}
+function toInboundMessage(raw) {
+    const parsed = parseGmailMessage(raw);
+    const attachments = [];
+    collectAttachments(raw.payload, attachments);
+    return {
+        attachments,
+        body_html: extractBody(raw.payload, "text/html"),
+        body_text: parsed.body_text,
+        cc: parsed.cc,
+        from_email: parsed.from_email,
+        from_name: parsed.from_name,
+        provider_message_id: parsed.message_id,
+        provider_thread_id: raw.threadId ?? null,
+        received_at: parsed.date,
+        subject: parsed.subject,
+        to: parsed.to,
+    };
+}
+/** Drafts and chats are never "inbound"; everything else flows through. */
+const EXCLUDED_LABELS = new Set(["CHAT", "DRAFT"]);
+const DEFAULT_PULL_LIMIT = 50;
+const MAX_PULL_LIMIT = 100;
+function parseBackfillCursor(cursor) {
+    if (!cursor.startsWith("{")) {
+        return null;
+    }
+    try {
+        const parsed = JSON.parse(cursor);
+        return parsed.backfill ?? null;
+    }
+    catch {
+        return null;
+    }
+}
+function backfillQuery(since) {
+    const sinceSeconds = since ? Math.floor(Date.parse(since) / 1000) : null;
+    const window = sinceSeconds !== null && Number.isFinite(sinceSeconds)
+        ? `after:${sinceSeconds}`
+        : "newer_than:30d";
+    return `${window} -in:chats -in:draft`;
+}
+function pullLimit(ctx) {
+    return Math.min(Math.max(ctx.limit ?? DEFAULT_PULL_LIMIT, 1), MAX_PULL_LIMIT);
+}
+// Gmail caps concurrent requests per user ("Too many concurrent requests",
+// 429 rateLimitExceeded) — fetch details in small chunks, never all at once.
+const DETAIL_FETCH_CONCURRENCY = 5;
+const RATE_LIMIT_RETRIES = 3;
+const RATE_LIMIT_BACKOFF_MS = 1000;
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+async function fetchMessageDetail(ctx, id) {
+    for (let attempt = 0;; attempt++) {
+        try {
+            return await googleJson(ctx, `${GMAIL_API}/messages/${encodeURIComponent(id)}?format=full`);
+        }
+        catch (error) {
+            // Deleted between listing and fetch — skip instead of failing the pull.
+            if (error instanceof Error && error.message.includes("(404)")) {
+                ctx.log("gmail stream: message vanished before fetch", { id });
+                return null;
+            }
+            // Transient rate limit — back off and retry before failing the pull.
+            if (error instanceof Error &&
+                error.message.includes("(429)") &&
+                attempt < RATE_LIMIT_RETRIES) {
+                const delay = RATE_LIMIT_BACKOFF_MS * 2 ** attempt;
+                ctx.log("gmail stream: rate limited, backing off", { delay, id });
+                await sleep(delay);
+                continue;
+            }
+            throw error;
+        }
+    }
+}
+async function fetchInboundMessages(ctx, ids) {
+    const messages = [];
+    for (let i = 0; i < ids.length; i += DETAIL_FETCH_CONCURRENCY) {
+        const chunk = ids.slice(i, i + DETAIL_FETCH_CONCURRENCY);
+        messages.push(...(await Promise.all(chunk.map((id) => fetchMessageDetail(ctx, id)))));
+    }
+    return messages
+        .filter((m) => m !== null)
+        .map(toInboundMessage);
+}
+/** First pull (or backfill continuation): messages.list over a date window. */
+async function pullBackfillPage(ctx, historyId, pageToken) {
+    const url = new URL(`${GMAIL_API}/messages`);
+    url.searchParams.set("q", backfillQuery(ctx.since));
+    url.searchParams.set("maxResults", String(pullLimit(ctx)));
+    if (pageToken) {
+        url.searchParams.set("pageToken", pageToken);
+    }
+    const list = await googleJson(ctx, url.toString());
+    const items = await fetchInboundMessages(ctx, (list.messages ?? []).map((m) => m.id));
+    return {
+        hasMore: Boolean(list.nextPageToken),
+        items,
+        nextCursor: list.nextPageToken
+            ? JSON.stringify({
+                backfill: { historyId, pageToken: list.nextPageToken },
+            })
+            : historyId,
+    };
+}
+/** Incremental pull: history.list from the cursor historyId. */
+async function pullIncremental(ctx, cursor) {
+    const limit = pullLimit(ctx);
+    const ids = new Set();
+    let pageToken;
+    let lastRecordId = null;
+    let latestHistoryId = null;
+    let stoppedEarly = false;
+    do {
+        const url = new URL(`${GMAIL_API}/history`);
+        url.searchParams.set("startHistoryId", cursor);
+        url.searchParams.set("historyTypes", "messageAdded");
+        url.searchParams.set("maxResults", "100");
+        if (pageToken) {
+            url.searchParams.set("pageToken", pageToken);
+        }
+        let data;
+        try {
+            data = await googleJson(ctx, url.toString());
+        }
+        catch (error) {
+            // Gmail expires history ids (~a week); the consumer must restart with
+            // a null cursor (its own dedupe absorbs the backfill overlap).
+            if (error instanceof Error && error.message.includes("(404)")) {
+                throw new Error("gmail_stream_cursor_expired: the history cursor is no longer valid; pull again with a null cursor to re-backfill");
+            }
+            throw error;
+        }
+        latestHistoryId = data.historyId ?? latestHistoryId;
+        for (const record of data.history ?? []) {
+            const added = (record.messagesAdded ?? [])
+                .map((m) => m.message)
+                .filter((m) => Boolean(m?.id) &&
+                !(m?.labelIds ?? []).some((l) => EXCLUDED_LABELS.has(l)));
+            if (ids.size + added.length > limit && ids.size > 0) {
+                // Stop BEFORE this record: history ids are only safe cursor points
+                // at record granularity (startHistoryId is exclusive).
+                stoppedEarly = true;
+                break;
+            }
+            for (const message of added) {
+                ids.add(message.id);
+            }
+            lastRecordId = record.id;
+        }
+        if (stoppedEarly) {
+            break;
+        }
+        pageToken = data.nextPageToken;
+    } while (pageToken);
+    const items = await fetchInboundMessages(ctx, [...ids]);
+    return {
+        hasMore: stoppedEarly,
+        items,
+        nextCursor: stoppedEarly
+            ? (lastRecordId ?? cursor)
+            : (latestHistoryId ?? cursor),
+    };
+}
+async function pullGmailStream(ctx, cursor) {
+    if (cursor === null) {
+        // Capture the mailbox history id BEFORE listing so the switch to
+        // incremental pulls never leaves a gap (overlap is deduped downstream
+        // by provider_message_id).
+        const profile = await googleJson(ctx, `${GMAIL_API}/profile`);
+        return pullBackfillPage(ctx, profile.historyId, null);
+    }
+    const backfill = parseBackfillCursor(cursor);
+    if (backfill) {
+        return pullBackfillPage(ctx, backfill.historyId, backfill.pageToken);
+    }
+    return pullIncremental(ctx, cursor);
+}
+// ─── RFC 822 assembly for drafts/sending ───
+function encodeHeaderValue(value) {
+    // RFC 2047 B-encoding for non-ASCII header values.
+    return /^[\x20-\x7e]*$/.test(value)
+        ? value
+        : `=?UTF-8?B?${Buffer.from(value, "utf-8").toString("base64")}?=`;
+}
+function buildRawMessage(input) {
+    const lines = [
+        `To: ${input.to.join(", ")}`,
+        ...(input.cc?.length ? [`Cc: ${input.cc.join(", ")}`] : []),
+        `Subject: ${encodeHeaderValue(input.subject)}`,
+        "MIME-Version: 1.0",
+        'Content-Type: text/plain; charset="UTF-8"',
+        "Content-Transfer-Encoding: 8bit",
+        "",
+        input.body_text,
+    ];
+    return Buffer.from(lines.join("\r\n"), "utf-8").toString("base64url");
+}
+// ─── Shared schema fragments ───
+const emailAddress = z.string().min(3);
+const composeFields = {
+    body_text: z.string().describe("Plain-text body of the email."),
+    cc: z
+        .array(emailAddress.describe("Cc recipient email address."))
+        .optional()
+        .describe("Optional list of Cc recipient email addresses."),
+    subject: z.string().describe("Email subject line."),
+    to: z
+        .array(emailAddress.describe("Recipient email address."))
+        .min(1)
+        .describe("List of recipient email addresses (To)."),
+};
+// ─── Connector ───
+export const gmailConnector = defineConnector({
+    actions: [
+        connectorAction({
+            description: "Fetch a Gmail attachment body by message id and attachment id (for inbox previews).",
+            group: "read",
+            handler: async (input, ctx) => {
+                const data = await googleJson(ctx, `${GMAIL_API}/messages/${encodeURIComponent(input.message_id)}/attachments/${encodeURIComponent(input.attachment_id)}`);
+                if (!data.data) {
+                    throw new Error("gmail attachment has no data");
+                }
+                return {
+                    data_base64: gmailAttachmentDataToBase64(data.data),
+                    size: data.size ?? null,
+                };
+            },
+            id: "get_attachment",
+            inputSchema: z.object({
+                attachment_id: z
+                    .string()
+                    .describe("Gmail attachment id from message metadata."),
+                message_id: z.string().describe("Gmail message id."),
+            }),
+            providerScopes: [SCOPE_READONLY],
+            summary: "Fetch a Gmail attachment",
+        }),
+        connectorAction({
+            description: "Search Gmail threads with a Gmail query string and return brief per-thread info (subject, sender, date, snippet, message count).",
+            group: "read",
+            handler: async (input, ctx) => {
+                const url = new URL(`${GMAIL_API}/threads`);
+                url.searchParams.set("q", input.q);
+                url.searchParams.set("maxResults", String(input.max_results ?? 10));
+                const list = await googleJson(ctx, url.toString());
+                const threads = list.threads ?? [];
+                const detailed = await Promise.all(threads.map(async (t) => {
+                    const detail = await googleJson(ctx, `${GMAIL_API}/threads/${encodeURIComponent(t.id)}?format=metadata&metadataHeaders=From&metadataHeaders=Subject&metadataHeaders=Date`);
+                    const messages = detail.messages ?? [];
+                    const last = messages.at(-1);
+                    const headers = last?.payload?.headers;
+                    return {
+                        from: getHeader(headers, "From") ?? null,
+                        last_message_at: last?.internalDate
+                            ? new Date(Number(last.internalDate)).toISOString()
+                            : (getHeader(headers, "Date") ?? null),
+                        message_count: messages.length,
+                        snippet: t.snippet ?? null,
+                        subject: getHeader(headers, "Subject") ?? null,
+                        thread_id: t.id,
+                    };
+                }));
+                return {
+                    result_size_estimate: list.resultSizeEstimate ?? detailed.length,
+                    threads: detailed,
+                };
+            },
+            id: "search_threads",
+            inputSchema: z.object({
+                max_results: z
+                    .number()
+                    .int()
+                    .min(1)
+                    .max(25)
+                    .optional()
+                    .describe("Maximum number of threads to return (1-25, default 10)."),
+                q: z
+                    .string()
+                    .describe('Gmail search query, same syntax as the Gmail search box (e.g. "from:alice@example.com is:unread newer_than:7d").'),
+            }),
+            providerScopes: [SCOPE_READONLY],
+            summary: "Search Gmail threads",
+        }),
+        connectorAction({
+            description: "Fetch a Gmail thread by id with all messages parsed: from/to/cc, subject, date and plain-text body.",
+            group: "read",
+            handler: async (input, ctx) => {
+                const thread = await googleJson(ctx, `${GMAIL_API}/threads/${encodeURIComponent(input.thread_id)}?format=full`);
+                return {
+                    message_count: thread.messages?.length ?? 0,
+                    messages: (thread.messages ?? []).map(parseGmailMessage),
+                    thread_id: thread.id,
+                };
+            },
+            id: "get_thread",
+            inputSchema: z.object({
+                thread_id: z
+                    .string()
+                    .describe("Gmail thread id (from search_threads results)."),
+            }),
+            providerScopes: [SCOPE_READONLY],
+            summary: "Read a full Gmail thread",
+        }),
+        connectorAction({
+            description: "List all Gmail labels (system and user-created) with their ids, for use with modify_labels.",
+            group: "read",
+            handler: async (_input, ctx) => {
+                const data = await googleJson(ctx, `${GMAIL_API}/labels`);
+                return {
+                    labels: (data.labels ?? []).map((l) => ({
+                        id: l.id,
+                        name: l.name,
+                        type: l.type ?? "user",
+                    })),
+                };
+            },
+            id: "list_labels",
+            inputSchema: z.object({}),
+            providerScopes: [SCOPE_READONLY],
+            summary: "List Gmail labels",
+        }),
+        connectorAction({
+            description: "List Gmail drafts with their ids, recipients and subjects.",
+            group: "read",
+            handler: async (input, ctx) => {
+                const url = new URL(`${GMAIL_API}/drafts`);
+                url.searchParams.set("maxResults", String(input.max_results ?? 10));
+                const list = await googleJson(ctx, url.toString());
+                const drafts = await Promise.all((list.drafts ?? []).map(async (d) => {
+                    const detail = await googleJson(ctx, `${GMAIL_API}/drafts/${encodeURIComponent(d.id)}?format=metadata`);
+                    const headers = detail.message?.payload?.headers;
+                    return {
+                        draft_id: d.id,
+                        message_id: detail.message?.id ?? d.message?.id ?? null,
+                        subject: getHeader(headers, "Subject") ?? null,
+                        thread_id: detail.message?.threadId ?? null,
+                        to: parseAddressList(getHeader(headers, "To")),
+                    };
+                }));
+                return { drafts };
+            },
+            id: "list_drafts",
+            inputSchema: z.object({
+                max_results: z
+                    .number()
+                    .int()
+                    .min(1)
+                    .max(25)
+                    .optional()
+                    .describe("Maximum number of drafts to return (1-25, default 10)."),
+            }),
+            providerScopes: [SCOPE_READONLY],
+            summary: "List Gmail drafts",
+        }),
+        connectorAction({
+            description: "Create a Gmail draft (plain text). The draft is saved but NOT sent; use send_message to actually send email.",
+            group: "write",
+            handler: async (input, ctx) => {
+                const result = await googleJson(ctx, `${GMAIL_API}/drafts`, {
+                    body: JSON.stringify({ message: { raw: buildRawMessage(input) } }),
+                    headers: { "Content-Type": "application/json" },
+                    method: "POST",
+                });
+                return {
+                    draft_id: result.id,
+                    message_id: result.message?.id ?? null,
+                    thread_id: result.message?.threadId ?? null,
+                };
+            },
+            id: "create_draft",
+            inputSchema: z.object(composeFields),
+            providerScopes: [SCOPE_COMPOSE, SCOPE_MODIFY],
+            summary: "Create a Gmail draft",
+        }),
+        connectorAction({
+            description: "Add and/or remove labels on a Gmail message (label ids from list_labels, e.g. STARRED, or a user label id).",
+            group: "write",
+            handler: async (input, ctx) => {
+                const result = await googleJson(ctx, `${GMAIL_API}/messages/${encodeURIComponent(input.message_id)}/modify`, {
+                    body: JSON.stringify({
+                        addLabelIds: input.add ?? [],
+                        removeLabelIds: input.remove ?? [],
+                    }),
+                    headers: { "Content-Type": "application/json" },
+                    method: "POST",
+                });
+                return {
+                    label_ids: result.labelIds ?? [],
+                    message_id: result.id,
+                    thread_id: result.threadId ?? null,
+                };
+            },
+            id: "modify_labels",
+            inputSchema: z
+                .object({
+                add: z
+                    .array(z.string().describe("Label id to add."))
+                    .optional()
+                    .describe("Label ids to add to the message."),
+                message_id: z.string().describe("Gmail message id to modify."),
+                remove: z
+                    .array(z.string().describe("Label id to remove."))
+                    .optional()
+                    .describe("Label ids to remove from the message."),
+            })
+                .refine((v) => (v.add?.length ?? 0) + (v.remove?.length ?? 0) > 0, {
+                message: "Provide at least one label id in add or remove.",
+            }),
+            providerScopes: [SCOPE_COMPOSE, SCOPE_MODIFY],
+            summary: "Modify Gmail message labels",
+        }),
+        connectorAction({
+            description: "Send an email via Gmail immediately (plain text). This delivers mail to the recipients — irreversible.",
+            group: "destructive",
+            handler: async (input, ctx) => {
+                const result = await googleJson(ctx, `${GMAIL_API}/messages/send`, {
+                    body: JSON.stringify({ raw: buildRawMessage(input) }),
+                    headers: { "Content-Type": "application/json" },
+                    method: "POST",
+                });
+                return {
+                    message_id: result.id,
+                    sent: true,
+                    thread_id: result.threadId ?? null,
+                };
+            },
+            id: "send_message",
+            inputSchema: z.object(composeFields),
+            providerScopes: [SCOPE_SEND],
+            summary: "Send an email via Gmail",
+        }),
+        connectorAction({
+            description: "Move a Gmail message to the trash (recoverable in Gmail for ~30 days).",
+            group: "destructive",
+            handler: async (input, ctx) => {
+                const result = await googleJson(ctx, `${GMAIL_API}/messages/${encodeURIComponent(input.message_id)}/trash`, { method: "POST" });
+                return {
+                    label_ids: result.labelIds ?? [],
+                    message_id: result.id,
+                    trashed: true,
+                };
+            },
+            id: "trash_message",
+            inputSchema: z.object({
+                message_id: z.string().describe("Gmail message id to move to trash."),
+            }),
+            providerScopes: [SCOPE_MODIFY],
+            summary: "Trash a Gmail message",
+        }),
+    ],
+    auth: { kind: "oauth2", oauth2: GOOGLE_OAUTH2 },
+    description: "Read, draft, label and send email in a connected Gmail account.",
+    icon: "logo:gmail",
+    id: "google-gmail",
+    moduleId: "connections-google",
+    name: "Gmail",
+    // Inbound message stream for module consumers (inbox, KB, …): incremental
+    // via history.list (cursor = historyId), initial backfill via messages.list
+    // over a date window. Never projected as an agent tool.
+    stream: { kind: "messages", pull: pullGmailStream },
+    toolPrefix: "gmail",
+});

package/apps/runtime/dist/engenty/connections-google/definitions.js

@@ -0,0 +1,11 @@
+import { calendarConnector } from "./connectors/calendar.js";
+import { contactsConnector } from "./connectors/contacts.js";
+import { driveConnector } from "./connectors/drive.js";
+import { gmailConnector } from "./connectors/gmail.js";
+/** All connectors this module registers, in registration order. */
+export const googleConnectors = [
+    gmailConnector,
+    driveConnector,
+    calendarConnector,
+    contactsConnector,
+];

package/apps/runtime/dist/engenty/connections-google/shared.js

@@ -0,0 +1,73 @@
+/**
+ * Shared Google OAuth2 config for all three connectors. One OAuth client
+ * (GOOGLE_OAUTH_CLIENT_ID/SECRET) covers Gmail, Drive and Calendar; scopes are
+ * requested incrementally per enabled action group
+ * (`include_granted_scopes=true`).
+ */
+export const GOOGLE_OAUTH2 = {
+    authUrl: "https://accounts.google.com/o/oauth2/v2/auth",
+    baseScopes: ["openid", "email"],
+    clientIdEnv: "GOOGLE_OAUTH_CLIENT_ID",
+    clientSecretEnv: "GOOGLE_OAUTH_CLIENT_SECRET",
+    extraAuthParams: {
+        access_type: "offline",
+        include_granted_scopes: "true",
+        prompt: "consent",
+    },
+    resolveAccount: async (accessToken, fetchImpl) => {
+        const res = await fetchImpl("https://www.googleapis.com/oauth2/v2/userinfo", {
+            headers: { Authorization: `Bearer ${accessToken}` },
+        });
+        if (!res.ok) {
+            throw new Error(`google_api_error (${res.status}): ${await errorExcerpt(res)}`);
+        }
+        const data = (await res.json());
+        return {
+            ...(data.id ? { externalId: data.id } : {}),
+            label: data.email ?? "Google account",
+        };
+    },
+    tokenUrl: "https://oauth2.googleapis.com/token",
+};
+async function errorExcerpt(res) {
+    const body = await res.text().catch(() => "");
+    return body.replace(/\s+/g, " ").trim().slice(0, 200) || res.statusText;
+}
+/**
+ * Bearer-authenticated fetch against a Google API. Throws
+ * `google_api_error (<status>): <short body excerpt>` on non-2xx responses.
+ */
+export async function googleFetch(ctx, url, init) {
+    const res = await ctx.fetchImpl(url, {
+        ...init,
+        headers: {
+            Authorization: `Bearer ${ctx.accessToken}`,
+            ...(init?.headers ?? {}),
+        },
+    });
+    if (!res.ok) {
+        throw new Error(`google_api_error (${res.status}): ${await errorExcerpt(res)}`);
+    }
+    return res;
+}
+/** googleFetch + JSON body. */
+export async function googleJson(ctx, url, init) {
+    const res = await googleFetch(ctx, url, init);
+    return (await res.json());
+}
+/**
+ * Build a `ConnectorAction` whose handler receives zod-parsed, typed input.
+ * The runtime hands the raw operation input straight to the handler, so each
+ * action validates against its own inputSchema before touching the provider.
+ */
+export function connectorAction(def) {
+    return {
+        description: def.description,
+        group: def.group,
+        handler: (input, ctx) => def.handler(def.inputSchema.parse(input), ctx),
+        id: def.id,
+        inputSchema: def.inputSchema,
+        providerScopes: def.providerScopes,
+        summary: def.summary,
+    };
+}