@oomol-lab/open-connector 1.6.5 → 1.8.0

package/src/providers/github/trigger-watch-pull-request.definition.d.ts

@@ -0,0 +1,4 @@
+import type { TriggerKeySnapshot } from "../../triggers/common/types.ts";
+export declare const snapshot: TriggerKeySnapshot & {
+    readonly type: "integration";
+};

package/src/providers/github/trigger-watch-pull-request.definition.js

@@ -0,0 +1,49 @@
+import { jsonSchema as s } from "../../core/json-schema.js";
+import { snapshot as githubRepoEventSnapshot } from "./trigger-on-repo-event.definition.js";
+const pullRequestSchema = s.object({
+    id: s.integer(),
+    number: s.integer(),
+    title: s.string(),
+    url: s.string(),
+    state: s.stringEnum(["open", "closed"]),
+    draft: s.boolean(),
+    merged: s.boolean(),
+    updatedAt: s.string(),
+    headSha: s.string(),
+    baseSha: s.string(),
+}, {
+    additionalProperties: false,
+    required: ["id", "number", "title", "url", "state", "draft", "merged", "updatedAt", "headSha", "baseSha"],
+});
+export const snapshot = {
+    configInputs: [
+        {
+            handle: "owner",
+            jsonSchema: s.string({ pattern: "^[a-zA-Z0-9](?:[a-zA-Z0-9]|-(?=[a-zA-Z0-9])){0,38}$" }),
+            nullable: false,
+        },
+        {
+            handle: "repo",
+            jsonSchema: s.string({ pattern: "^(?!\\.{1,2}$)[a-zA-Z0-9._-]{1,100}$" }),
+            nullable: false,
+        },
+        {
+            handle: "number",
+            jsonSchema: s.integer({ minimum: 1 }),
+            nullable: false,
+            description: "Number of the pull request to watch.",
+        },
+    ],
+    definitionVersion: 2,
+    description: "Watches one pull request using notifications and periodic checks. Starts from its current state; reports observed changes, not every intermediate transition or review event.",
+    displayName: "Watch Pull Request",
+    endpoint: githubRepoEventSnapshot.endpoint,
+    key: "github.watch_pull_request",
+    name: "watch_pull_request",
+    provider: "github",
+    type: "integration",
+    outputs: [
+        { handle: "pullRequest", jsonSchema: pullRequestSchema, nullable: false },
+        { handle: "version", jsonSchema: s.string(), nullable: false },
+    ],
+};

package/src/providers/github/trigger-watch-pull-request.js

@@ -0,0 +1,106 @@
+import { canonicalJsonBytes, digestBytes } from "../../triggers/common/encoding.js";
+import { IntegrationConnectionError, PermanentIntegrationError, TransientIntegrationError, } from "../../triggers/common/integration.js";
+import { isJsonObject } from "../../triggers/common/json.js";
+import { githubRepoEvent } from "./trigger-on-repo-event.js";
+import { snapshot } from "./trigger-watch-pull-request.definition.js";
+function hookConfig(config) {
+    return { owner: config.owner, repo: config.repo, events: ["pull_request"], insecureSsl: false };
+}
+export const githubPullRequestListener = {
+    snapshot,
+    initialState: { checkpoint: null, subscription: {} },
+    async reconcile(context) {
+        if (context.state == null)
+            throw new PermanentIntegrationError("GitHub listener state is missing.");
+        if (context.active && context.state.checkpoint == null) {
+            const current = await readPullRequest(context);
+            await context.state.saveCheckpoint({ version: current.version, sequence: 0 });
+        }
+        return await githubRepoEvent.reconcile({ ...context, config: hookConfig(context.config) });
+    },
+    async receive(context) {
+        const received = await githubRepoEvent.receive({
+            ...context,
+            config: hookConfig(context.config),
+        });
+        if (received.outcome != "event")
+            return received;
+        if (!isJsonObject(context.payload) || context.payload.number !== context.config.number)
+            return { outcome: "ignored", reason: "Different pull request." };
+        return { outcome: "wake" };
+    },
+    listener: {
+        intervalMs: 300_000,
+        async read(context) {
+            const checkpoint = context.checkpoint;
+            if (!isJsonObject(checkpoint) ||
+                typeof checkpoint.version != "string" ||
+                !Number.isSafeInteger(checkpoint.sequence) ||
+                Number(checkpoint.sequence) < 0 ||
+                Number(checkpoint.sequence) >= Number.MAX_SAFE_INTEGER) {
+                throw new PermanentIntegrationError("GitHub listener checkpoint is invalid.");
+            }
+            const current = await readPullRequest(context);
+            if (current.version == checkpoint.version)
+                return { checkpoint, dedupeKey: current.version, hasMore: false, outputs: null };
+            const sequence = Number(checkpoint.sequence) + 1;
+            return {
+                checkpoint: { version: current.version, sequence },
+                dedupeKey: `${sequence}:${current.version}`,
+                hasMore: false,
+                outputs: current,
+            };
+        },
+    },
+};
+async function readPullRequest(context) {
+    const { owner, repo, number } = context.config;
+    if (typeof owner != "string" || typeof repo != "string" || !Number.isSafeInteger(number) || Number(number) < 1)
+        throw new PermanentIntegrationError("GitHub pull request configuration is invalid.");
+    const result = await context.connector.execute({
+        endpoint: `/repos/${encodeURIComponent(owner)}/${encodeURIComponent(repo)}/pulls/${number}`,
+        method: "GET",
+    }, context.signal);
+    context.signal?.throwIfAborted();
+    const value = result.data;
+    if (result.status == 429 ||
+        (result.status == 403 &&
+            isJsonObject(value) &&
+            typeof value.message == "string" &&
+            /rate limit/i.test(value.message)))
+        throw new TransientIntegrationError("GitHub pull request checks were rate limited.");
+    if (result.status == 401 || result.status == 403)
+        throw new IntegrationConnectionError("GitHub pull request access requires authorization.");
+    if (result.status == 404)
+        throw new PermanentIntegrationError("The pull request is unavailable; it may no longer be accessible.");
+    if (result.status != 200)
+        throw new TransientIntegrationError(`GitHub pull request check failed with status ${result.status}.`);
+    if (!isJsonObject(value) ||
+        !Number.isSafeInteger(value.id) ||
+        value.number !== number ||
+        typeof value.title != "string" ||
+        typeof value.html_url != "string" ||
+        (value.state != "open" && value.state != "closed") ||
+        typeof value.draft != "boolean" ||
+        typeof value.merged != "boolean" ||
+        typeof value.updated_at != "string" ||
+        !Number.isFinite(Date.parse(value.updated_at)) ||
+        !isJsonObject(value.head) ||
+        typeof value.head.sha != "string" ||
+        !isJsonObject(value.base) ||
+        typeof value.base.sha != "string")
+        throw new TransientIntegrationError("GitHub returned an invalid pull request.");
+    const pullRequest = {
+        id: Number(value.id),
+        number: Number(number),
+        title: value.title,
+        url: value.html_url,
+        state: value.state,
+        draft: value.draft,
+        merged: value.merged,
+        updatedAt: value.updated_at,
+        headSha: value.head.sha,
+        baseSha: value.base.sha,
+    };
+    return { pullRequest, version: await digestBytes(canonicalJsonBytes(pullRequest)) };
+}

package/src/providers/gitlab/executors.d.ts

@@ -1,4 +1,6 @@
 import type { CredentialValidators, ProviderExecutors, ProviderProxyExecutor } from "../../core/types.ts";
+import type { IntegrationDefinition } from "../../triggers/common/integration.ts";
+import type { PollDefinition } from "../../triggers/common/poll.ts";
 import type { ProviderActionHandlers } from "../provider-runtime.ts";
 type GitlabActionInput = Record<string, unknown>;
 type GitlabActionHandler = (input: GitlabActionInput, context: GitlabActionContext) => Promise<unknown>;
@@ -23,4 +25,5 @@ export declare const credentialValidators: CredentialValidators;
  * `allowPrivateNetwork` may be passed explicitly (used by tests).
  */
 export declare function normalizeGitlabApiBaseUrl(value: unknown, allowPrivateNetwork?: boolean): string;
+export declare const triggers: readonly (IntegrationDefinition | PollDefinition)[];
 export {};

package/src/providers/gitlab/executors.js

@@ -1,6 +1,7 @@
 import { compactObject, optionalBoolean, optionalIntegerLike, optionalRecord, optionalString as asOptionalString, recordOrEmpty, } from "../../core/cast.js";
 import { assertPublicHttpUrl, isPrivateNetworkAccessAllowed } from "../../core/request.js";
 import { createProviderFetch, defineProviderExecutors, defineProviderProxy, providerInputError, ProviderRequestError, providerUserAgent, } from "../provider-runtime.js";
+import { gitlabProjectEvent } from "./trigger-on-project-event.js";
 const defaultGitlabApiBaseUrl = "https://gitlab.com/api/v4";
 const service = "gitlab";
 export const gitlabActionHandlers = {
@@ -515,3 +516,4 @@ function asOptionalPositiveInteger(value, fieldName) {
     }
     return parsed;
 }
+export const triggers = [gitlabProjectEvent];

package/src/providers/gitlab/trigger-on-project-event.d.ts

@@ -0,0 +1,2 @@
+import type { IntegrationDefinition } from "../../triggers/common/integration.ts";
+export declare const gitlabProjectEvent: IntegrationDefinition;

package/src/providers/gitlab/trigger-on-project-event.definition.d.ts

@@ -0,0 +1,5 @@
+import type { TriggerKeySnapshot } from "../../triggers/common/types.ts";
+export declare const events: readonly string[];
+export declare const snapshot: TriggerKeySnapshot & {
+    readonly type: "integration";
+};

package/src/providers/gitlab/trigger-on-project-event.definition.js

@@ -0,0 +1,63 @@
+import { jsonSchema as s } from "../../core/json-schema.js";
+export const events = [
+    "push",
+    "tag_push",
+    "issues",
+    "confidential_issues",
+    "note",
+    "confidential_note",
+    "merge_requests",
+    "job",
+    "pipeline",
+    "wiki_page",
+    "deployment",
+    "feature_flag",
+    "releases",
+    "milestone",
+    "emoji",
+    "resource_access_token",
+    "resource_deploy_token",
+];
+export const snapshot = {
+    configInputs: [
+        {
+            handle: "events",
+            jsonSchema: s.array(s.stringEnum(events), { minItems: 1, uniqueItems: true }),
+            nullable: false,
+        },
+        { handle: "insecureSsl", jsonSchema: s.boolean(), nullable: false, value: false },
+        {
+            handle: "project",
+            jsonSchema: s.string({
+                maxLength: 255,
+                minLength: 1,
+                pattern: "^(?:[0-9]+|(?!\\.{1,2}(?:/|$))[A-Za-z0-9_.][A-Za-z0-9_.-]*(?:/(?!\\.{1,2}(?:/|$))[A-Za-z0-9_.][A-Za-z0-9_.-]*)*)$",
+            }),
+            nullable: false,
+        },
+        {
+            handle: "pushBranchFilter",
+            jsonSchema: s.string({ maxLength: 255 }),
+            nullable: false,
+            value: "",
+        },
+    ],
+    definitionVersion: 2,
+    description: "Triggers when selected GitLab webhook events occur in a project.",
+    displayName: "Project Event",
+    endpoint: {
+        body: { allowArray: false, allowEmpty: false, formats: ["json"] },
+        methods: ["POST"],
+        successStatus: 202,
+    },
+    key: "gitlab.on_project_event",
+    name: "on_project_event",
+    outputs: [
+        { handle: "body", jsonSchema: { type: "object" }, nullable: false },
+        { handle: "deliveryId", jsonSchema: s.string(), nullable: false },
+        { handle: "event", jsonSchema: s.string(), nullable: false },
+        { handle: "gitlabEvent", jsonSchema: s.string(), nullable: false },
+    ],
+    provider: "gitlab",
+    type: "integration",
+};

package/src/providers/gitlab/trigger-on-project-event.js

@@ -0,0 +1,186 @@
+import { IntegrationConnectionError, PermanentIntegrationError, TransientIntegrationError, } from "../../triggers/common/integration.js";
+import { sameSecret } from "../../triggers/signature.js";
+import { snapshot, events } from "./trigger-on-project-event.definition.js";
+const eventNames = new Map([
+    ["Push Hook", "push"],
+    ["Tag Push Hook", "tag_push"],
+    ["Issue Hook", "issues"],
+    ["Confidential Issue Hook", "confidential_issues"],
+    ["Note Hook", "note"],
+    ["Confidential Note Hook", "confidential_note"],
+    ["Merge Request Hook", "merge_requests"],
+    ["Job Hook", "job"],
+    ["Pipeline Hook", "pipeline"],
+    ["Wiki Page Hook", "wiki_page"],
+    ["Deployment Hook", "deployment"],
+    ["Feature Flag Hook", "feature_flag"],
+    ["Release Hook", "releases"],
+    ["Milestone Hook", "milestone"],
+    ["Emoji Hook", "emoji"],
+    ["Resource Access Token Hook", "resource_access_token"],
+    ["Resource Deploy Token Hook", "resource_deploy_token"],
+]);
+export const gitlabProjectEvent = {
+    initialState: { checkpoint: null, subscription: {} },
+    snapshot,
+    receive(context) {
+        if (!sameSecret(context.header("x-gitlab-token"), context.callbackSecret)) {
+            return { body: "", contentType: "text/plain", outcome: "respond", status: 404 };
+        }
+        const gitlabEvent = context.header("x-gitlab-event")?.trim();
+        if (!gitlabEvent)
+            return { outcome: "ignored", reason: "GitLab event header is missing." };
+        const event = eventNames.get(gitlabEvent);
+        if (event == null)
+            return { outcome: "ignored", reason: "GitLab event header is unknown." };
+        if (!resolveConfig(context.config).events.includes(event))
+            return { outcome: "ignored", reason: "GitLab event is not subscribed." };
+        const deliveryId = context.header("idempotency-key") ?? "";
+        return {
+            dedupeKey: deliveryId.length == 0 ? undefined : deliveryId,
+            outcome: "event",
+            outputs: {
+                body: context.payload,
+                deliveryId,
+                event,
+                gitlabEvent,
+            },
+        };
+    },
+    async reconcile(context) {
+        const state = requireState(context.state);
+        const config = resolveConfig(context.config);
+        const known = subscriptionId(state);
+        if (!context.active) {
+            const ids = known == null ? await findByUrl(context, config) : [known];
+            for (const id of ids ?? [])
+                await remove(context, config, id);
+            await state.saveSubscription({}, later(context.now));
+            return { outcome: "ready" };
+        }
+        const matches = await findByUrl(context, config);
+        if (matches == null)
+            throw new PermanentIntegrationError("The GitLab project does not exist or is not visible.");
+        let hookId = known ?? matches[0];
+        if (hookId == null) {
+            const created = await request(context, "hook create", {
+                body: desired(context.endpointUrl, context.callbackSecret, config),
+                endpoint: endpoint(config),
+                method: "POST",
+            });
+            success(created, "hook create");
+            hookId = readId(created.data);
+        }
+        else {
+            const aligned = await request(context, "hook update", {
+                body: desired(context.endpointUrl, context.callbackSecret, config),
+                endpoint: `${endpoint(config)}/${hookId}`,
+                method: "PUT",
+            });
+            if (aligned.status == 404) {
+                await state.saveSubscription({}, context.now);
+                return { outcome: "pending" };
+            }
+            success(aligned, "hook update");
+        }
+        for (const duplicate of matches.filter((value) => value != hookId))
+            await remove(context, config, duplicate);
+        await state.saveSubscription({ hookId }, later(context.now));
+        return { outcome: "ready" };
+    },
+};
+function resolveConfig(value) {
+    return {
+        events: value.events,
+        insecureSsl: value.insecureSsl,
+        project: value.project,
+        pushBranchFilter: value.pushBranchFilter,
+    };
+}
+function endpoint(config) {
+    return `/projects/${encodeURIComponent(config.project)}/hooks`;
+}
+function desired(url, token, config) {
+    return {
+        branch_filter_strategy: "wildcard",
+        description: "Managed by Open Flow.",
+        enable_ssl_verification: !config.insecureSsl,
+        name: `Open Flow ${url.slice(url.lastIndexOf("/") + 1)}`,
+        push_events_branch_filter: config.pushBranchFilter,
+        url,
+        token,
+        ...Object.fromEntries(events.map((event) => [`${event}_events`, config.events.includes(event)])),
+    };
+}
+async function findByUrl(context, config) {
+    const matches = [];
+    for (let page = 1; page <= 10; page += 1) {
+        const result = await request(context, "hook list", {
+            endpoint: endpoint(config),
+            method: "GET",
+            query: { page, per_page: 100 },
+        });
+        if (result.status == 404)
+            return null;
+        success(result, "hook list");
+        const hooks = Array.isArray(result.data) ? result.data : [];
+        for (const hook of hooks) {
+            const value = record(hook);
+            if (value?.url === context.endpointUrl && (typeof value.id == "number" || typeof value.id == "string"))
+                matches.push(String(value.id));
+        }
+        if (hooks.length < 100)
+            break;
+    }
+    return matches;
+}
+async function remove(context, config, hookId) {
+    const result = await request(context, "hook delete", {
+        endpoint: `${endpoint(config)}/${hookId}`,
+        method: "DELETE",
+    });
+    if (result.status != 404)
+        success(result, "hook delete");
+}
+async function request(context, operation, value) {
+    try {
+        return await context.connector.execute(value, context.signal);
+    }
+    catch (cause) {
+        if (cause instanceof IntegrationConnectionError)
+            throw cause;
+        throw new TransientIntegrationError(`GitLab ${operation} request failed.`, { cause });
+    }
+}
+function success(result, operation) {
+    if (result.status >= 200 && result.status < 300)
+        return;
+    if (result.status == 401 || result.status == 403)
+        throw new IntegrationConnectionError(`GitLab ${operation} rejected the Connection.`);
+    if ([400, 404, 422].includes(result.status))
+        throw new PermanentIntegrationError(`GitLab ${operation} rejected the subscription.`);
+    throw new TransientIntegrationError(`GitLab ${operation} failed with status ${result.status}.`);
+}
+function readId(data) {
+    const value = record(data)?.id;
+    if (typeof value != "number" && typeof value != "string")
+        throw new TransientIntegrationError("GitLab hook response is missing its ID.");
+    return String(value);
+}
+function requireState(value) {
+    if (value == null)
+        throw new PermanentIntegrationError("GitLab Integration state is missing.");
+    return value;
+}
+function subscriptionId(state) {
+    const value = state.subscription.hookId;
+    return typeof value == "string" && value.length > 0 ? value : null;
+}
+function later(now) {
+    return new Date(now.getTime() + 30 * 24 * 60 * 60 * 1_000);
+}
+function record(value) {
+    return value != null && typeof value == "object" && !Array.isArray(value)
+        ? value
+        : undefined;
+}

package/src/providers/gmail/executors.d.ts

@@ -1,4 +1,6 @@
 import type { CredentialValidators, ExecutionContext, ProviderExecutors, ProviderProxyExecutor } from "../../core/types.ts";
+import type { IntegrationDefinition } from "../../triggers/common/integration.ts";
+import type { PollDefinition } from "../../triggers/common/poll.ts";
 import type { ProviderActionHandlers } from "../provider-runtime.ts";
 declare const service = "gmail";
 interface ActionContext {
@@ -13,4 +15,5 @@ export declare const gmailActionHandlers: ProviderActionHandlers<typeof service,
 export declare const executors: ProviderExecutors;
 export declare const proxy: ProviderProxyExecutor;
 export declare const credentialValidators: CredentialValidators;
+export declare const triggers: readonly (IntegrationDefinition | PollDefinition)[];
 export {};

package/src/providers/gmail/executors.js

@@ -1,10 +1,11 @@
 import { looseArray, optionalRecord, optionalString } from "../../core/cast.js";
 import { encodePathSegment } from "../../core/request.js";
-import { googleBearerProxyAuth, googleServiceAccountValidator, resolveGoogleAccessToken } from "../google-auth.js";
-import { defineProviderExecutors, defineProviderProxy, ProviderRequestError, readProviderErrorTextBody, readProviderJsonBody, requiredInputString, runProviderRequest, } from "../provider-runtime.js";
+import { googleBearerProxyAuth, googleServiceAccountValidator, resolveGoogleAccessToken, } from "../googledrive/runtime-auth.js";
+import { defineProviderExecutors, defineProviderProxy, ProviderRequestError, readProviderErrorTextBody, readProviderJsonBody, requiredInputString, runProviderRequest, withRetryAfterSeconds, } from "../provider-runtime.js";
 import { decodeGmailAttachment } from "./attachment-stream.js";
 import { buildRecipients, encodeMimeMessage, extractBodyContent, firstAddress, normalizeGmailMessage, normalizeMessageId, normalizeThreadId, parseAddressList, readHeader, resolveReplyHeaders, summarizeGmailMessage, } from "./message.js";
 import { gmailOAuthScopes } from "./scopes.js";
+import { gmailMessageReceived } from "./trigger-on-message-received.js";
 const service = "gmail";
 const gmailApiBaseUrl = "https://gmail.googleapis.com/gmail/v1";
 const detailHydrationBatchSize = 10;
@@ -787,5 +788,6 @@ async function readGmailError(response) {
     }
     const rateLimited = response.status === 403 &&
         looseArray(error?.errors).some((entry) => gmailQuotaReasons.has(optionalString(optionalRecord(entry)?.reason) ?? ""));
-    return new ProviderRequestError(response.status, optionalString(error?.message) ?? `gmail request failed with ${response.status}`, undefined, rateLimited ? "rate_limited" : undefined);
+    return new ProviderRequestError(response.status, optionalString(error?.message) ?? `gmail request failed with ${response.status}`, withRetryAfterSeconds(response), rateLimited ? "rate_limited" : undefined);
 }
+export const triggers = [gmailMessageReceived];

package/src/providers/gmail/message.d.ts

@@ -20,6 +20,7 @@ export interface GmailMessageResource {
     internalDate?: string;
     labelIds?: string[];
     snippet?: string;
+    sizeEstimate?: number;
     raw?: string;
     payload?: GmailMessagePart;
 }
@@ -39,13 +40,7 @@ export interface GmailAttachmentSummary {
     mimeType: string;
     size: number;
 }
-export interface NormalizedGmailMessage {
-    messageId: string;
-    threadId: string;
-    labelIds: string[];
-    subject: string;
-    sender: string;
-    to: string;
+export interface NormalizedGmailMessage extends GmailMessageSummary {
     preview: {
         subject: string;
         body: string;
@@ -53,7 +48,6 @@ export interface NormalizedGmailMessage {
     payload: GmailMessagePart | null;
     messageText: string;
     attachmentList: GmailAttachmentSummary[];
-    messageTimestamp: string;
     raw?: string;
 }
 export interface GmailMessageSummary {
@@ -64,6 +58,10 @@ export interface GmailMessageSummary {
     sender: string;
     to: string;
     messageTimestamp: string;
+    historyId?: string;
+    internalDate?: string;
+    sizeEstimate?: number;
+    snippet?: string;
 }
 export interface MimeMessageInput {
     to: string[];

package/src/providers/gmail/message.js

@@ -8,6 +8,10 @@ export function summarizeGmailMessage(resource) {
         sender: readHeader(headers, "From"),
         to: readHeader(headers, "To"),
         messageTimestamp: toMessageTimestamp(resource.internalDate, readHeader(headers, "Date")),
+        historyId: resource.historyId,
+        internalDate: resource.internalDate,
+        sizeEstimate: resource.sizeEstimate,
+        snippet: resource.snippet,
     };
 }
 export function normalizeGmailMessage(resource) {

package/src/providers/gmail/scopes.d.ts

@@ -10,4 +10,36 @@ export declare const gmailComposeScopes: string[];
 export declare const gmailSendScopes: string[];
 export declare const gmailLabelScopes: string[];
 export declare const gmailSettingsBasicScopes: string[];
+/**
+ * The scopes a SERVICE ACCOUNT token is minted for, and the ones the proxy
+ * resolves with. Unchanged: a domain-wide-delegation grant lists these exact
+ * scopes in the Workspace admin console, and a token request naming a scope the
+ * admin has not authorized fails outright — so this list cannot grow without
+ * breaking every existing service-account connection.
+ */
 export declare const gmailOAuthScopes: string[];
+/**
+ * The scopes a user OAuth authorization may request — the menu, not a minimum.
+ *
+ * `gmail.readonly` is here and not in {@link gmailOAuthScopes} because the two
+ * lists answer different questions. That one asks "what does a service account
+ * token need to cover every action"; `modify` subsumes `readonly` there, so
+ * adding it would be redundant at best and, through domain-wide delegation,
+ * breaking at worst.
+ *
+ * This one is what `filterDeclaredScopes` intersects a caller's
+ * `requestedScopes` against, so a scope absent here cannot be requested AT ALL.
+ * Leaving `readonly` out therefore forced every read-only integration to
+ * authorize `gmail.modify` — write, label and trash on the user's mailbox — in
+ * order to call actions that declare `gmailReadScopes`. That is the opposite of
+ * least privilege, and it is invisible: consent succeeds, so nothing reports
+ * that more was granted than the integration can use.
+ *
+ * Note for anyone storing a client config WITHOUT `requestedScopes`:
+ * `getEffectiveScopes` falls back to this whole list, so such a config now asks
+ * for four scopes rather than three. `readonly` is subsumed by `modify`, so no
+ * new capability is granted — but the consent screen gains a line, and a
+ * deployment that wants the narrow set should say so explicitly with
+ * `requestedScopes`, which is the correct posture regardless.
+ */
+export declare const gmailAuthorizableScopes: string[];

package/src/providers/gmail/scopes.js

@@ -10,4 +10,41 @@ export const gmailComposeScopes = [gmailComposeScope];
 export const gmailSendScopes = [gmailSendScope];
 export const gmailLabelScopes = [gmailLabelsScope];
 export const gmailSettingsBasicScopes = [gmailSettingsBasicScope];
+/**
+ * The scopes a SERVICE ACCOUNT token is minted for, and the ones the proxy
+ * resolves with. Unchanged: a domain-wide-delegation grant lists these exact
+ * scopes in the Workspace admin console, and a token request naming a scope the
+ * admin has not authorized fails outright — so this list cannot grow without
+ * breaking every existing service-account connection.
+ */
 export const gmailOAuthScopes = [gmailModifyScope, gmailLabelsScope, gmailSettingsBasicScope];
+/**
+ * The scopes a user OAuth authorization may request — the menu, not a minimum.
+ *
+ * `gmail.readonly` is here and not in {@link gmailOAuthScopes} because the two
+ * lists answer different questions. That one asks "what does a service account
+ * token need to cover every action"; `modify` subsumes `readonly` there, so
+ * adding it would be redundant at best and, through domain-wide delegation,
+ * breaking at worst.
+ *
+ * This one is what `filterDeclaredScopes` intersects a caller's
+ * `requestedScopes` against, so a scope absent here cannot be requested AT ALL.
+ * Leaving `readonly` out therefore forced every read-only integration to
+ * authorize `gmail.modify` — write, label and trash on the user's mailbox — in
+ * order to call actions that declare `gmailReadScopes`. That is the opposite of
+ * least privilege, and it is invisible: consent succeeds, so nothing reports
+ * that more was granted than the integration can use.
+ *
+ * Note for anyone storing a client config WITHOUT `requestedScopes`:
+ * `getEffectiveScopes` falls back to this whole list, so such a config now asks
+ * for four scopes rather than three. `readonly` is subsumed by `modify`, so no
+ * new capability is granted — but the consent screen gains a line, and a
+ * deployment that wants the narrow set should say so explicitly with
+ * `requestedScopes`, which is the correct posture regardless.
+ */
+export const gmailAuthorizableScopes = [
+    gmailReadonlyScope,
+    gmailModifyScope,
+    gmailLabelsScope,
+    gmailSettingsBasicScope,
+];

package/src/providers/gmail/trigger-on-message-received.d.ts

@@ -0,0 +1,2 @@
+import type { PollDefinition } from "../../triggers/common/poll.ts";
+export declare const gmailMessageReceived: PollDefinition;

package/src/providers/gmail/trigger-on-message-received.definition.d.ts

@@ -0,0 +1,4 @@
+import type { TriggerKeySnapshot } from "../../triggers/common/types.ts";
+export declare const snapshot: TriggerKeySnapshot & {
+    readonly type: "poll";
+};