@oomol-lab/open-connector 1.7.0 → 1.9.0

package/src/providers/gmail/mime.js

@@ -0,0 +1,481 @@
+import iconv from "iconv-lite";
+import { Buffer } from "node:buffer";
+import { providerInputError, providerResponseError, ProviderRequestError } from "../provider-runtime.js";
+import { gmailMaxMimeBytes } from "./limits.js";
+/** Read a draft's subject and reply identity without changing or traversing its MIME body. */
+export function readMimeReplyHeaders(original) {
+    const root = parseEntity(decodeRaw(original));
+    return {
+        encodedSubject: Buffer.from(headerValue(root, "Subject"), "latin1").toString("utf8"),
+        inReplyTo: headerValue(root, "In-Reply-To"),
+        references: headerValue(root, "References"),
+    };
+}
+/** Decode RFC 2047 subject words from Gmail payload or raw MIME headers. */
+export function decodeMimeSubject(value) {
+    const unfolded = value.replace(/\r?\n[ \t]+/g, " ");
+    const joined = unfolded.replace(/(=\?[^?\s]+\?[bq]\?[^?]*\?=)[ \t]+(?==\?[^?\s]+\?[bq]\?[^?]*\?=)/gi, "$1");
+    return joined.replace(/=\?([^?\s]+)\?([bq])\?([^?]*)\?=/gi, (_word, charset, encoding, text) => {
+        const bytes = encoding.toLowerCase() === "b"
+            ? Buffer.from(text, "base64")
+            : Buffer.from(text
+                .replace(/_/g, " ")
+                .replace(/=([0-9a-f]{2})/gi, (_escape, hex) => String.fromCharCode(Number.parseInt(hex, 16))), "latin1");
+        try {
+            // RFC 2231 adds an optional language tag to the charset token.
+            const charsetName = charset.split("*", 1)[0];
+            let decoder;
+            try {
+                decoder = new TextDecoder(charsetName, { fatal: true });
+            }
+            catch {
+                // Fall back for unsupported charsets, never for invalid bytes in a supported charset.
+                return iconv.decode(bytes, charsetName);
+            }
+            return decoder.decode(bytes);
+        }
+        catch {
+            throw providerResponseError("Gmail subject has an invalid or unsupported RFC 2047 encoded word");
+        }
+    });
+}
+/** Encode a Gmail message with caller-supplied attachments and CID resources. */
+export function encodeMimeMessage(input) {
+    const headers = messageHeaders(input);
+    const attachmentParts = (input.attachments ?? []).map(encodeAttachment);
+    const inline = attachmentParts.filter((part) => part.inline).map((part) => part.raw);
+    const attachments = attachmentParts.filter((part) => !part.inline).map((part) => part.raw);
+    const content = composeContent(encodeBody(input.body ?? "", input.isHtml === true), inline, attachments);
+    return encodeRaw([...headers, "MIME-Version: 1.0", content].join("\r\n"));
+}
+/**
+ * Patch headers without touching the original MIME body. Explicit content edits
+ * support ordinary mixed/related/alternative mail and keep opaque file parts.
+ */
+export function updateMimeMessage(original, patch) {
+    if (patch.isHtml !== undefined && patch.body === undefined) {
+        throw providerInputError("isHtml requires body or messageBody when updating a draft");
+    }
+    const raw = decodeRaw(original);
+    const root = parseEntity(raw);
+    let headers = patchMessageHeaders(root.headers, patch, root.newline);
+    if (patch.body === undefined && patch.attachments === undefined) {
+        return encodeRaw(renderEntity(headers, root.body, root.newline));
+    }
+    const contentRoot = parseEntity(renderEntity(root.headers.filter(isContentHeader), root.body, root.newline));
+    const existing = decomposeContent(contentRoot, patch.body !== undefined, 0, true);
+    const body = patch.body === undefined ? existing.body : encodeBody(patch.body, patch.isHtml ?? existing.isHtml);
+    let inline = existing.inline;
+    let attachments = existing.attachments;
+    if (patch.attachments !== undefined) {
+        const parts = patch.attachments.map(encodeAttachment);
+        inline = parts.filter((part) => part.inline).map((part) => part.raw);
+        attachments = parts.filter((part) => !part.inline).map((part) => part.raw);
+    }
+    else {
+        const contentIds = new Set();
+        for (const rawPart of inline) {
+            const id = headerValue(parseEntity(rawPart), "Content-ID").trim();
+            if (!id)
+                continue;
+            if (contentIds.has(id))
+                throw unsupportedMime("retained inline parts have duplicate Content-ID; supply a replacement attachments list");
+            contentIds.add(id);
+        }
+    }
+    const content = composeContent(body, inline, attachments, existing.preamble, existing.epilogue);
+    headers = headers.filter((header) => !isContentHeader(header) && header.name.toLowerCase() !== "mime-version");
+    const rebuilt = parseEntity(content);
+    const retainedHeaders = [...headers, ...rebuilt.headers].map((header) => header.raw.replace(/\r?\n/g, "\r\n"));
+    retainedHeaders.push("MIME-Version: 1.0");
+    return encodeRaw(`${retainedHeaders.join("\r\n")}\r\n\r\n${rebuilt.body}`);
+}
+/** Reject header delimiters before encoding can conceal them in an encoded word. */
+function assertMimeHeaderValue(value, field) {
+    const allowsTab = field === "subject" || field === "In-Reply-To" || field === "References";
+    for (const char of value) {
+        const code = char.charCodeAt(0);
+        if ((code <= 0x1f && !(code === 0x09 && allowsTab)) || code === 0x7f)
+            throw providerInputError(`${field} must not contain control characters`);
+    }
+}
+function messageHeaders(input) {
+    const headers = [];
+    for (const [name, value] of headerValues(input)) {
+        if (value !== undefined && (value !== "" || name === "Subject")) {
+            headers.push(foldHeader(name, value));
+        }
+    }
+    return headers;
+}
+function headerValues(input) {
+    if (input.inReplyTo !== undefined)
+        assertMimeHeaderValue(input.inReplyTo, "In-Reply-To");
+    if (input.references !== undefined)
+        assertMimeHeaderValue(input.references, "References");
+    return new Map([
+        ["From", input.from === undefined ? undefined : encodeAddress(input.from)],
+        ["To", input.to === undefined ? undefined : input.to.map(encodeAddress).join(", ")],
+        ["Cc", input.cc === undefined ? undefined : input.cc.map(encodeAddress).join(", ")],
+        ["Bcc", input.bcc === undefined ? undefined : input.bcc.map(encodeAddress).join(", ")],
+        ["Subject", input.subject === undefined ? undefined : encodeWords(input.subject, "subject")],
+        ["In-Reply-To", input.inReplyTo],
+        ["References", input.references],
+    ]);
+}
+function patchMessageHeaders(headers, patch, newline) {
+    const result = [...headers];
+    for (const [name, value] of headerValues(patch)) {
+        if (value === undefined)
+            continue;
+        assertMimeHeaderValue(value.replace(/\r\n /g, " "), name);
+        const index = result.findIndex((header) => header.name.toLowerCase() === name.toLowerCase());
+        const retained = result.filter((header) => header.name.toLowerCase() !== name.toLowerCase());
+        if (value !== "" || name === "Subject") {
+            retained.splice(index < 0 ? retained.length : index, 0, {
+                name,
+                value,
+                raw: foldHeader(name, value).replace(/\r\n/g, newline),
+            });
+        }
+        result.splice(0, result.length, ...retained);
+    }
+    return result;
+}
+function encodeBody(body, isHtml) {
+    if (Buffer.byteLength(body, "utf8") > gmailMaxMimeBytes)
+        throw tooLarge("Gmail message body");
+    return `Content-Type: ${isHtml ? "text/html" : "text/plain"}; charset=UTF-8\r\nContent-Transfer-Encoding: base64\r\n\r\n${foldBase64(Buffer.from(body, "utf8").toString("base64"))}`;
+}
+/** Validate attachment header metadata for both input resolution and MIME encoding. */
+export function assertMimeAttachmentMetadata(attachment) {
+    assertMimeHeaderValue(attachment.mimeType, "attachment.mimeType");
+    if (!/^[a-z0-9!#$&^_.+-]+\/[a-z0-9!#$&^_.+-]+$/i.test(attachment.mimeType)) {
+        throw providerInputError("attachment.mimeType must be a type/subtype without parameters");
+    }
+    if (attachment.filename !== undefined) {
+        assertMimeHeaderValue(attachment.filename, "attachment.filename");
+        if (attachment.filename.length === 0)
+            throw providerInputError("attachment.filename must not be empty");
+        if (!attachment.filename.isWellFormed())
+            throw providerInputError("attachment.filename must contain valid Unicode");
+    }
+    if (attachment.contentId !== undefined) {
+        assertMimeHeaderValue(attachment.contentId, "attachment.contentId");
+        if (!/^[\x21-\x7e]+$/.test(attachment.contentId) || /[<>:]/.test(attachment.contentId)) {
+            throw providerInputError("attachment.contentId must be a bare ASCII ID without cid: or angle brackets");
+        }
+    }
+    if (attachment.disposition === "inline" && !attachment.contentId) {
+        throw providerInputError("inline attachments require contentId");
+    }
+}
+function encodeAttachment(attachment) {
+    assertMimeAttachmentMetadata(attachment);
+    const headers = [`Content-Type: ${attachment.mimeType}`, "Content-Transfer-Encoding: base64"];
+    let disposition = `Content-Disposition: ${attachment.disposition}`;
+    if (attachment.filename !== undefined)
+        disposition += filenameParameters(attachment.filename);
+    headers.push(disposition);
+    if (attachment.contentId !== undefined)
+        headers.push(`Content-ID: <${attachment.contentId}>`);
+    if (headers.some((header) => header.split("\r\n").some((line) => Buffer.byteLength(line, "utf8") > 998))) {
+        throw providerInputError("attachment headers exceed the MIME line length limit");
+    }
+    return {
+        raw: `${headers.join("\r\n")}\r\n\r\n${foldBase64(attachment.contentBase64)}`,
+        inline: attachment.disposition === "inline",
+    };
+}
+function filenameParameters(filename) {
+    // Keep an ASCII fallback for older clients and RFC 2231 UTF-8 continuations for the actual name.
+    const fallback = filename
+        .replace(/[^\x20-\x7e]/g, "_")
+        .slice(0, 120)
+        .replace(/[\\"]/g, "\\$&");
+    const encoded = encodeURIComponent(filename).replace(/[!'()*]/g, (char) => `%${char.charCodeAt(0).toString(16).toUpperCase()}`);
+    const chunks = encoded.match(/(?:%[0-9a-f]{2}|[^%]){1,45}/gi) ?? [""];
+    return `;\r\n filename="${fallback}"${chunks.map((chunk, index) => `;\r\n filename*${index}*=${index === 0 ? "UTF-8''" : ""}${chunk}`).join("")}`;
+}
+function composeContent(body, inline, attachments, preamble = "", epilogue = "") {
+    let result = body;
+    if (inline.length > 0)
+        result = encodeMultipart("related", [result, ...inline]);
+    if (attachments.length > 0)
+        result = encodeMultipart("mixed", [result, ...attachments]);
+    // A framing-only mixed wrapper retains MIME preambles/epilogues even after clearing all files.
+    if (preamble || epilogue) {
+        const parsed = parseEntity(result);
+        if (mimeHeader(parsed, "Content-Type").token.startsWith("multipart/")) {
+            result = renderEntity(parsed.headers, `${preamble}${parsed.body}${epilogue}`, parsed.newline);
+        }
+        else {
+            result = encodeMultipart("mixed", [result], preamble, epilogue);
+        }
+    }
+    return result;
+}
+function encodeMultipart(kind, parts, preamble = "", epilogue = "") {
+    let boundary;
+    do {
+        boundary = `oomol_${crypto.randomUUID()}`;
+    } while (parts.some((part) => part.includes(boundary)) || preamble.includes(boundary) || epilogue.includes(boundary));
+    const prefix = preamble && !preamble.endsWith("\n") ? `${preamble}\r\n` : preamble;
+    const type = kind === "related" ? `; type="${mimeHeader(parseEntity(parts[0]), "Content-Type").token || "text/plain"}"` : "";
+    return `Content-Type: multipart/${kind}${type}; boundary="${boundary}"\r\n\r\n${prefix}${parts.map((part) => `--${boundary}\r\n${part}\r\n`).join("")}--${boundary}--\r\n${epilogue}`;
+}
+function decomposeContent(entity, replaceBody, depth = 0, isRelatedRoot = false) {
+    if (depth > 20)
+        throw unsupportedMime("MIME nesting is too deep");
+    const type = mimeHeader(entity, "Content-Type");
+    const empty = {
+        body: entity.raw,
+        isHtml: type.token === "text/html",
+        inline: [],
+        attachments: [],
+        preamble: "",
+        epilogue: "",
+    };
+    if (type.token === "text/plain" || type.token === "text/html" || type.token === "") {
+        if (isAttachmentEntity(entity, isRelatedRoot))
+            throw unsupportedMime("the draft has no editable message body");
+        return empty;
+    }
+    if (!["multipart/mixed", "multipart/related", "multipart/alternative"].includes(type.token)) {
+        throw unsupportedMime(`content type ${type.token || "unknown"}`);
+    }
+    const multipart = parseMultipart(entity, type.parameters.get("boundary"));
+    if (type.token === "multipart/alternative") {
+        const alternatives = multipart.parts.map((part) => decomposeContent(part, replaceBody, depth + 1, true));
+        if (alternatives.length === 0)
+            throw unsupportedMime("empty multipart/alternative");
+        const hasHtml = alternatives.some((part) => part.isHtml);
+        return {
+            body: replaceBody
+                ? ""
+                : renderEntity(entity.headers, renderOriginalMultipart(entity, multipart, alternatives.map((part) => part.body)), entity.newline),
+            isHtml: hasHtml,
+            inline: alternatives.flatMap((part) => part.inline),
+            attachments: alternatives.flatMap((part) => part.attachments),
+            preamble: (replaceBody ? multipart.preamble : "") + alternatives.map((part) => part.preamble).join(""),
+            epilogue: alternatives.map((part) => part.epilogue).join("") + (replaceBody ? multipart.epilogue : ""),
+        };
+    }
+    let bodyIndex = 0;
+    if (type.token === "multipart/related") {
+        const start = type.parameters.get("start");
+        if (start) {
+            bodyIndex = multipart.parts.findIndex((part) => headerValue(part, "Content-ID").trim() === start.trim());
+            if (bodyIndex < 0)
+                throw unsupportedMime("multipart/related start does not identify its body");
+        }
+    }
+    else {
+        const candidates = multipart.parts
+            .map((part, index) => (isBodyEntity(part, index === 0) ? index : -1))
+            .filter((index) => index >= 0);
+        if (candidates.length !== 1)
+            throw unsupportedMime("multipart/mixed has an ambiguous message body");
+        bodyIndex = candidates[0];
+    }
+    const bodyPart = multipart.parts[bodyIndex];
+    if (!bodyPart)
+        throw unsupportedMime("multipart body is missing");
+    // Related roots may carry Content-ID to match the container's start parameter.
+    const content = decomposeContent(bodyPart, replaceBody, depth + 1, true);
+    for (let index = 0; index < multipart.parts.length; index++) {
+        if (index === bodyIndex)
+            continue;
+        const part = multipart.parts[index];
+        const inline = type.token === "multipart/related" || mimeHeader(part, "Content-Disposition").token === "inline";
+        (inline ? content.inline : content.attachments).push(part.raw);
+    }
+    content.preamble = multipart.preamble + content.preamble;
+    content.epilogue += multipart.epilogue;
+    return content;
+}
+function isBodyEntity(entity, isBodyRoot) {
+    if (isAttachmentEntity(entity, isBodyRoot))
+        return false;
+    const type = mimeHeader(entity, "Content-Type").token;
+    return (type === "text/plain" ||
+        type === "text/html" ||
+        type === "" ||
+        ["multipart/alternative", "multipart/related", "multipart/mixed"].includes(type));
+}
+function isAttachmentEntity(entity, isRelatedRoot = false) {
+    const disposition = mimeHeader(entity, "Content-Disposition");
+    const type = mimeHeader(entity, "Content-Type");
+    return (disposition.token === "attachment" ||
+        disposition.parameters.has("filename") ||
+        [...disposition.parameters.keys()].some((key) => key.startsWith("filename*")) ||
+        type.parameters.has("name") ||
+        (!isRelatedRoot && headerValue(entity, "Content-ID") !== ""));
+}
+function parseEntity(raw) {
+    let separator = /\r\n\r\n|\n\n/.exec(raw);
+    if (raw.startsWith("\r\n") || raw.startsWith("\n"))
+        separator = /^(?:\r\n|\n)/.exec(raw);
+    // The CRLF introducing a multipart boundary may also finish an empty part's separator.
+    if (!separator)
+        separator = /(?:\r\n|\n)$/.exec(raw);
+    if (!separator)
+        throw providerResponseError("Gmail raw draft has no MIME header separator");
+    const newline = separator[0].startsWith("\r") ? "\r\n" : "\n";
+    const headerText = raw.slice(0, separator.index);
+    const headers = [];
+    if (headerText) {
+        for (const line of headerText.split(/\r?\n/)) {
+            if (/^[ \t]/.test(line)) {
+                const previous = headers.at(-1);
+                if (!previous)
+                    throw providerResponseError("Gmail raw draft has an invalid folded header");
+                previous.raw += newline + line;
+                previous.value += " " + line.trim();
+                continue;
+            }
+            const match = /^([!#$%&'*+.^_`|~a-z0-9-]+):[ \t]*(.*)$/i.exec(line);
+            if (!match)
+                throw providerResponseError("Gmail raw draft has an invalid MIME header");
+            headers.push({ name: match[1], value: match[2], raw: line });
+        }
+    }
+    return { headers, body: raw.slice(separator.index + separator[0].length), raw, newline };
+}
+function parseMultipart(entity, boundary) {
+    if (!boundary || boundary.length > 70 || /[^\x20-\x7e]|[\r\n]/.test(boundary))
+        throw unsupportedMime("invalid multipart boundary");
+    const escaped = boundary.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+    const delimiters = [...entity.body.matchAll(new RegExp(`^--${escaped}(--)?[ \\t]*(?:\\r?\\n|$)`, "gm"))];
+    if (delimiters.length < 2 ||
+        delimiters[0][1] ||
+        !delimiters.at(-1)[1] ||
+        delimiters.slice(0, -1).some((match) => match[1])) {
+        throw unsupportedMime("incomplete multipart boundaries");
+    }
+    if (delimiters.length > 1001)
+        throw unsupportedMime("too many MIME parts");
+    const parts = delimiters.slice(0, -1).map((delimiter, index) => {
+        const start = delimiter.index + delimiter[0].length;
+        const next = delimiters[index + 1].index;
+        const end = entity.body.slice(0, next).endsWith("\r\n") ? next - 2 : next - 1;
+        if (end < start)
+            throw unsupportedMime("empty MIME part framing");
+        return parseEntity(entity.body.slice(start, end));
+    });
+    const closing = delimiters.at(-1);
+    return {
+        parts,
+        preamble: entity.body.slice(0, delimiters[0].index),
+        epilogue: entity.body.slice(closing.index + closing[0].length),
+    };
+}
+function renderOriginalMultipart(entity, multipart, parts) {
+    const boundary = mimeHeader(entity, "Content-Type").parameters.get("boundary");
+    return `${multipart.preamble}${parts.map((part) => `--${boundary}${entity.newline}${part}${entity.newline}`).join("")}--${boundary}--${entity.newline}${multipart.epilogue}`;
+}
+function mimeHeader(entity, name) {
+    const parsed = parseMimeHeader(headerValue(entity, name));
+    if (parsed.duplicateParameters)
+        throw unsupportedMime(`duplicate ${name} parameter`);
+    return parsed;
+}
+/** Read MIME media types and quoted parameters from Gmail payload headers. */
+export function parseMimeHeader(value) {
+    const parameters = new Map();
+    let duplicateParameters = false;
+    for (const match of value.matchAll(/;[ \t]*([a-z0-9*-]+)[ \t]*=[ \t]*(?:"((?:[^"\\]|\\.)*)"|([^; \t]+))/gi)) {
+        const key = match[1].toLowerCase();
+        if (parameters.has(key))
+            duplicateParameters = true;
+        else
+            parameters.set(key, match[2] === undefined ? match[3] : match[2].replace(/\\(.)/g, "$1"));
+    }
+    return { token: value.split(";", 1)[0].trim().toLowerCase(), parameters, duplicateParameters };
+}
+function headerValue(entity, name) {
+    const values = entity.headers.filter((header) => header.name.toLowerCase() === name.toLowerCase());
+    if (values.length > 1)
+        throw unsupportedMime(`duplicate ${name} header`);
+    return values[0]?.value ?? "";
+}
+function isContentHeader(header) {
+    return header.name.toLowerCase().startsWith("content-");
+}
+function renderHeaders(headers, newline) {
+    return headers.map((header) => header.raw).join(newline);
+}
+function renderEntity(headers, body, newline) {
+    const prefix = headers.length > 0 ? `${renderHeaders(headers, newline)}${newline}` : "";
+    return `${prefix}${newline}${body}`;
+}
+function encodeAddress(address) {
+    assertMimeHeaderValue(address, "email address");
+    const match = /^(.*?)\s*<([^<>]+)>$/.exec(address);
+    if (match && /[^\x20-\x7f]/.test(match[1])) {
+        const displayName = match[1].trim().replace(/^"(.*)"$/, "$1");
+        return `${encodeWords(displayName, "display name")} <${match[2]}>`;
+    }
+    return address;
+}
+function encodeWords(value, field) {
+    assertMimeHeaderValue(value, field);
+    if (!/[^\x20-\x7f]/.test(value) && !/=\?[^?\s]+\?[bq]\?[^?]*\?=/i.test(value))
+        return value;
+    const chunks = [];
+    let current = "";
+    for (const char of value) {
+        if (Buffer.byteLength(current + char, "utf8") > 45) {
+            chunks.push(current);
+            current = "";
+        }
+        current += char;
+    }
+    if (current)
+        chunks.push(current);
+    return chunks.map((chunk) => `=?UTF-8?B?${Buffer.from(chunk, "utf8").toString("base64")}?=`).join("\r\n ");
+}
+function foldHeader(name, value) {
+    // Only our RFC 2047 folds are permitted; raw caller values were checked before encoding.
+    assertMimeHeaderValue(value.replace(/\r\n /g, " "), name);
+    let line = `${name}:`;
+    const lines = [];
+    for (const word of value.replace(/\r\n /g, " ").split(" ")) {
+        if (Buffer.byteLength(`${line} ${word}`, "utf8") > 78 && line !== `${name}:`) {
+            lines.push(line);
+            line = "";
+        }
+        line += ` ${word}`;
+        if (Buffer.byteLength(line, "utf8") > 998)
+            throw providerInputError(`${name} exceeds the MIME line length limit`);
+    }
+    lines.push(line);
+    return Buffer.from(lines.join("\r\n"), "utf8").toString("latin1");
+}
+function foldBase64(value) {
+    return value.replace(/.{76}(?=.)/g, "$&\r\n");
+}
+function encodeRaw(raw) {
+    if (raw.length > gmailMaxMimeBytes)
+        throw tooLarge("Gmail MIME message");
+    const bytes = Buffer.from(raw, "latin1");
+    if (bytes.byteLength > gmailMaxMimeBytes)
+        throw tooLarge("Gmail MIME message");
+    return bytes.toString("base64url");
+}
+function decodeRaw(encoded) {
+    if (encoded.length > Math.ceil((gmailMaxMimeBytes * 4) / 3) + 4)
+        throw tooLarge("Gmail raw draft");
+    const bytes = Buffer.from(encoded, "base64url");
+    if (bytes.toString("base64url") !== encoded.replace(/=+$/, ""))
+        throw providerResponseError("Gmail raw draft is not valid base64url");
+    if (bytes.byteLength > gmailMaxMimeBytes)
+        throw tooLarge("Gmail raw draft");
+    return bytes.toString("latin1");
+}
+function unsupportedMime(reason) {
+    return providerInputError(`Cannot safely edit this draft's MIME content: ${reason}. Header-only updates are supported.`);
+}
+function tooLarge(field) {
+    return new ProviderRequestError(413, `${field} exceeds ${gmailMaxMimeBytes} bytes`);
+}

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

@@ -19,7 +19,8 @@ export declare const gmailSettingsBasicScopes: string[];
  */
 export declare const gmailOAuthScopes: string[];
 /**
- * The scopes a user OAuth authorization may request — the menu, not a minimum.
+ * Default user OAuth scopes. Together with gmailOptionalScopes, these form
+ * 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
@@ -27,8 +28,8 @@ export declare const gmailOAuthScopes: string[];
  * 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.
+ * `filterDeclaredScopes` intersects a caller's `requestedScopes` against this
+ * list and gmailOptionalScopes, so a scope absent from both cannot be requested.
  * 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
@@ -36,10 +37,12 @@ export declare const gmailOAuthScopes: string[];
  * 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
+ * `getEffectiveScopes` falls back to this whole list, so such a config asks
+ * for the same four default scopes. `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[];
+/** Narrow compose and send grants, available only through requestedScopes. */
+export declare const gmailOptionalScopes: string[];

package/src/providers/gmail/scopes.js

@@ -19,7 +19,8 @@ export const gmailSettingsBasicScopes = [gmailSettingsBasicScope];
  */
 export const gmailOAuthScopes = [gmailModifyScope, gmailLabelsScope, gmailSettingsBasicScope];
 /**
- * The scopes a user OAuth authorization may request — the menu, not a minimum.
+ * Default user OAuth scopes. Together with gmailOptionalScopes, these form
+ * 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
@@ -27,8 +28,8 @@ export const gmailOAuthScopes = [gmailModifyScope, gmailLabelsScope, gmailSettin
  * 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.
+ * `filterDeclaredScopes` intersects a caller's `requestedScopes` against this
+ * list and gmailOptionalScopes, so a scope absent from both cannot be requested.
  * 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
@@ -36,8 +37,8 @@ export const gmailOAuthScopes = [gmailModifyScope, gmailLabelsScope, gmailSettin
  * 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
+ * `getEffectiveScopes` falls back to this whole list, so such a config asks
+ * for the same four default scopes. `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.
@@ -48,3 +49,5 @@ export const gmailAuthorizableScopes = [
     gmailLabelsScope,
     gmailSettingsBasicScope,
 ];
+/** Narrow compose and send grants, available only through requestedScopes. */
+export const gmailOptionalScopes = [gmailComposeScope, gmailSendScope];

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";
+};

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

@@ -0,0 +1,74 @@
+import { jsonSchema as s } from "../../core/json-schema.js";
+const defaultPageSize = 25;
+const eventSchema = s.object({
+    historyId: { type: ["string", "null"] },
+    labelIds: s.array(s.string()),
+    messageId: s.string(),
+    messageTimestamp: s.string(),
+    sender: s.string(),
+    subject: s.string(),
+    threadId: s.string(),
+    to: s.string(),
+}, {
+    additionalProperties: false,
+    required: ["messageId", "threadId", "historyId", "labelIds", "subject", "sender", "to", "messageTimestamp"],
+});
+export const snapshot = {
+    configInputs: [
+        {
+            handle: "includeDrafts",
+            jsonSchema: s.boolean(),
+            nullable: false,
+            value: false,
+            description: "Also trigger on draft messages.",
+        },
+        {
+            handle: "includeSpamAndTrash",
+            jsonSchema: s.boolean(),
+            nullable: false,
+            value: false,
+            description: "Also trigger on messages in SPAM and TRASH.",
+        },
+        {
+            handle: "labelNamesOrIds",
+            jsonSchema: s.array(s.string({ minLength: 1 })),
+            nullable: false,
+            description: "Only trigger on messages carrying all of these labels, referenced by name or ID.",
+            value: [],
+        },
+        {
+            handle: "maxMessagesPerPoll",
+            jsonSchema: s.integer({ maximum: 100, minimum: 1 }),
+            nullable: false,
+            value: defaultPageSize,
+        },
+        {
+            handle: "readStatus",
+            jsonSchema: s.stringEnum(["Read", "Unread", "All"]),
+            nullable: false,
+            value: "All",
+        },
+        {
+            handle: "search",
+            jsonSchema: s.string(),
+            nullable: false,
+            description: "Gmail search-syntax query the message must match.",
+            value: "",
+        },
+        {
+            handle: "sender",
+            jsonSchema: s.string(),
+            nullable: false,
+            description: "Only trigger on messages whose sender matches this address or name.",
+            value: "",
+        },
+    ],
+    definitionVersion: 2,
+    description: "Polls the Gmail mailbox and triggers when a new message is received.",
+    displayName: "New Message Received",
+    key: "gmail.on_message_received",
+    name: "on_message_received",
+    outputs: [{ handle: "events", jsonSchema: s.array(eventSchema), nullable: false }],
+    provider: "gmail",
+    type: "poll",
+};