@protobase/workflow-plugins 0.71.1 → 0.71.3

package/dist/gmail/api.js

@@ -0,0 +1,85 @@
+import { ConnectionError, ResponseTooLargeError } from "@protobase/workflows/plugin";
+//#region src/gmail/api.ts
+/** Gmail answered 404: an expired history id, or a message deleted since it was listed. */
+var GmailNotFound = class extends Error {
+	name = "GmailNotFound";
+};
+/** A Gmail id as it may go into a path: letters and digits only, so no answer can steer a request elsewhere. */
+const gmailId = /^[A-Za-z0-9]{1,64}$/;
+/** A history id: a number, as text. */
+const historyId = /^\d{1,30}$/;
+const errorStatuses = /* @__PURE__ */ new Set([
+	"CANCELLED",
+	"UNKNOWN",
+	"INVALID_ARGUMENT",
+	"DEADLINE_EXCEEDED",
+	"NOT_FOUND",
+	"ALREADY_EXISTS",
+	"PERMISSION_DENIED",
+	"RESOURCE_EXHAUSTED",
+	"FAILED_PRECONDITION",
+	"ABORTED",
+	"OUT_OF_RANGE",
+	"UNIMPLEMENTED",
+	"INTERNAL",
+	"UNAVAILABLE",
+	"DATA_LOSS",
+	"UNAUTHENTICATED"
+]);
+const statusOf = (body) => {
+	const status = parseJson(body)?.error?.status;
+	return typeof status === "string" && errorStatuses.has(status) ? ` (${status})` : "";
+};
+const parseJson = (text) => {
+	try {
+		return JSON.parse(text);
+	} catch (error) {
+		if (!(error instanceof SyntaxError)) throw error;
+		return;
+	}
+};
+/**
+* The few read-only Gmail calls the trigger makes, all GET, through the plugin context's `fetch`. The token goes only in
+* the `Authorization` header, asked for once a poll; a 401 asks for it again and tries once more, and a second 401 is an
+* expired sign-in. An error names the call and its status, never a URL, a header or Google's own message.
+*/
+const gmailApi = ({ origin, fetch, connection, signal }) => {
+	if (!connection) throw new Error("Not implemented: the Gmail trigger always declares its Google connection");
+	let token;
+	const send = async (url, call, bearer, maxBytes) => {
+		try {
+			return await fetch(url, {
+				headers: {
+					authorization: `Bearer ${bearer}`,
+					accept: "application/json"
+				},
+				signal,
+				...maxBytes !== void 0 && { maxBytes }
+			});
+		} catch (error) {
+			if (error instanceof ResponseTooLargeError || signal.aborted) throw error;
+			throw new Error(`Gmail ${call} failed: ${error instanceof Error ? error.name : "unknown error"}`, { cause: error });
+		}
+	};
+	/** GET `path` with `query`, a list of names and values so a name may repeat; a value left undefined is left out. */
+	const get = async (path, query, call, maxBytes) => {
+		const params = new URLSearchParams(query.filter((entry) => entry[1] !== void 0));
+		const url = `${origin}/gmail/v1/users/me/${path}${params.size > 0 ? `?${params}` : ""}`;
+		token ??= await connection.accessToken();
+		let answer = await send(url, call, token, maxBytes);
+		if (answer.status === 401) {
+			token = await connection.accessToken();
+			answer = await send(url, call, token, maxBytes);
+			if (answer.status === 401) throw new ConnectionError("link_expired", "Google refused the access token twice: sign in to the Google account again");
+		}
+		const text = await answer.text();
+		if (answer.status === 404) throw new GmailNotFound(`Gmail ${call} found nothing`);
+		if (!answer.ok) throw new Error(`Gmail ${call} answered ${answer.status}${statusOf(text)}`);
+		const body = parseJson(text);
+		if (typeof body !== "object" || body === null) throw new Error(`Gmail ${call} answered no JSON object`);
+		return body;
+	};
+	return { get };
+};
+//#endregion
+export { GmailNotFound, gmailApi, gmailId, historyId };

package/dist/gmail/calls.js

@@ -0,0 +1,114 @@
+import { gmailId, historyId } from "./api.js";
+//#region src/gmail/calls.ts
+const bad = (call) => /* @__PURE__ */ new Error(`Gmail ${call} answered an unexpected shape`);
+const pageToken = (value, call) => {
+	if (value === void 0) return;
+	if (typeof value !== "string" || value.length === 0 || value.length > 1e3) throw bad(call);
+	return value;
+};
+const messageRef = (value, call) => {
+	const { id, threadId } = value ?? {};
+	if (typeof id !== "string" || !gmailId.test(id) || typeof threadId !== "string" || !gmailId.test(threadId)) throw bad(call);
+	return {
+		id,
+		threadId
+	};
+};
+const base64url = (text) => {
+	const binary = atob(text.replaceAll("-", "+").replaceAll("_", "/"));
+	const bytes = new Uint8Array(binary.length);
+	for (let index = 0; index < binary.length; index++) bytes[index] = binary.charCodeAt(index);
+	return bytes;
+};
+const list = (value, call) => {
+	if (value === void 0) return [];
+	if (!Array.isArray(value)) throw bad(call);
+	return value;
+};
+/** The mailbox's current history id (`users.getProfile`). */
+const profile = async (api) => {
+	const body = await api.get("profile", [], "getProfile");
+	if (typeof body.historyId !== "string" || !historyId.test(body.historyId)) throw bad("getProfile");
+	return body.historyId;
+};
+/** The mailbox's labels, by id and name (`users.labels.list`). */
+const labels = async (api) => {
+	const body = await api.get("labels", [], "labels.list");
+	return list(body.labels, "labels.list").map((label) => {
+		const { id, name } = label ?? {};
+		if (typeof id !== "string" || typeof name !== "string") throw bad("labels.list");
+		return {
+			id,
+			name
+		};
+	});
+};
+/** One page of the added messages after `start` on `label` (`users.history.list`). */
+const historyPage = async (api, { start, label, page }) => {
+	const call = "history.list";
+	const body = await api.get("history", [
+		["startHistoryId", start],
+		["historyTypes", "messageAdded"],
+		["labelId", label],
+		["maxResults", "100"],
+		["pageToken", page]
+	], call);
+	if (typeof body.historyId !== "string" || !historyId.test(body.historyId)) throw bad(call);
+	return {
+		records: list(body.history, call).map((record) => {
+			const { id, messagesAdded } = record ?? {};
+			if (typeof id !== "string" || !historyId.test(id)) throw bad(call);
+			return {
+				id,
+				added: list(messagesAdded, call).map((added) => messageRef(added?.message, call))
+			};
+		}),
+		next: pageToken(body.nextPageToken, call),
+		historyId: body.historyId
+	};
+};
+/** One page of at most `limit` messages on `label` after the time `since`, in seconds (`users.messages.list`). */
+const messagesPage = async (api, { label, since, page, limit }) => {
+	const call = "messages.list";
+	const body = await api.get("messages", [
+		["labelIds", label],
+		["q", `after:${since}`],
+		["maxResults", String(limit)],
+		["pageToken", page]
+	], call);
+	return {
+		messages: list(body.messages, call).map((message) => messageRef(message, call)),
+		next: pageToken(body.nextPageToken, call)
+	};
+};
+/** The headers a message's metadata gives, for a mail too large to read whole. */
+const metadataHeaders = [
+	"From",
+	"To",
+	"Cc",
+	"Subject",
+	"Date"
+];
+/** A message's whole RFC 822 source (`users.messages.get`, `format=raw`), at most `maxBytes` of answer. */
+const rawMessage = async (api, id, maxBytes) => {
+	const call = "messages.get";
+	const body = await api.get(`messages/${encodeURIComponent(id)}`, [["format", "raw"]], call, maxBytes);
+	if (typeof body.raw !== "string" || !/^[A-Za-z0-9_-]*={0,2}$/.test(body.raw)) throw bad(call);
+	return base64url(body.raw);
+};
+/** A message's headers alone (`users.messages.get`, `format=metadata`). */
+const messageHeaders = async (api, id) => {
+	const call = "messages.get";
+	const query = [["format", "metadata"], ...metadataHeaders.map((name) => ["metadataHeaders", name])];
+	const body = await api.get(`messages/${encodeURIComponent(id)}`, query, call);
+	return list(body.payload?.headers, call).map((header) => {
+		const { name, value } = header ?? {};
+		if (typeof name !== "string" || typeof value !== "string") throw bad(call);
+		return {
+			name,
+			value
+		};
+	});
+};
+//#endregion
+export { historyPage, labels, messageHeaders, messagesPage, metadataHeaders, profile, rawMessage };

package/dist/gmail/cursor.js

@@ -0,0 +1,35 @@
+import { historyId } from "./api.js";
+//#region src/gmail/cursor.ts
+/** A Gmail label id, such as `INBOX` or `Label_12`, as it goes into a query. */
+const labelId = /^[A-Za-z0-9_-]{1,100}$/;
+const seconds = (value) => Number.isSafeInteger(value) && value >= 0;
+const historyText = (value) => typeof value === "string" && historyId.test(value);
+/** The cursor a poll got back as the trigger stored it, checked field by field; one that does not fit fails the poll. */
+const readCursor = (value) => {
+	const cursor = value ?? {};
+	const label = cursor.label_id;
+	if (typeof label !== "string" || !labelId.test(label) || !seconds(cursor.polled_at)) throw new Error("The Gmail trigger has a cursor it cannot read");
+	if (cursor.recovery === void 0) {
+		if (!historyText(cursor.history_id) || !seconds(cursor.offset)) throw new Error("The Gmail trigger has a cursor it cannot read");
+		return {
+			label_id: label,
+			history_id: cursor.history_id,
+			offset: cursor.offset,
+			polled_at: cursor.polled_at
+		};
+	}
+	const { since, page_token: page, resume_history_id: resume } = cursor.recovery ?? {};
+	const pageFits = page === null || typeof page === "string" && page.length > 0 && page.length <= 1e3;
+	if (!seconds(since) || !pageFits || !historyText(resume)) throw new Error("The Gmail trigger has a cursor it cannot read");
+	return {
+		label_id: label,
+		polled_at: cursor.polled_at,
+		recovery: {
+			since,
+			page_token: page,
+			resume_history_id: resume
+		}
+	};
+};
+//#endregion
+export { labelId, readCursor };

package/dist/gmail/filters.js

@@ -0,0 +1,10 @@
+//#region src/gmail/filters.ts
+const contains = (value, part) => value !== null && value.toLowerCase().includes(part.toLowerCase());
+const anyAddress = (list, part) => list.some(({ name, address }) => contains(name, part) || contains(address, part));
+/**
+* Whether a mail passes every filter that is set: `from` on the sender's name or address, `to` on any To or Cc
+* recipient, `subject` on the subject. A mail without the value a set filter reads does not pass.
+*/
+const passes = (item, { from, to, subject }) => (from === void 0 || anyAddress(item.from ? [item.from] : [], from)) && (to === void 0 || anyAddress([...item.to, ...item.cc], to)) && (subject === void 0 || contains(item.subject, subject));
+//#endregion
+export { passes };

package/dist/gmail/history-walk.js

@@ -0,0 +1,53 @@
+/**
+* The first `limit` messages added after `start`, skipping `offset` messages of its first record, and where the next
+* walk starts: inside a record, the record before it (or `start`) with the messages of it now taken; at a record's end,
+* that record; after the last record of the last page, the mailbox's current history id, the only place it is used,
+* and `caughtUp`.
+*/
+const walkHistory = async (read, start, offset, limit) => {
+	const taken = [];
+	let before = start;
+	let skip = offset;
+	let page;
+	for (let pages = 0; pages < 10; pages++) {
+		const answer = await read(page);
+		for (const [index, record] of answer.records.entries()) {
+			const left = record.added.slice(skip);
+			const room = limit - taken.length;
+			if (left.length > room) {
+				taken.push(...left.slice(0, room));
+				return {
+					taken,
+					history_id: before,
+					offset: skip + room,
+					caughtUp: false
+				};
+			}
+			taken.push(...left);
+			before = record.id;
+			skip = 0;
+			const last = index === answer.records.length - 1 && answer.next === void 0;
+			if (taken.length === limit && !last) return {
+				taken,
+				history_id: record.id,
+				offset: 0,
+				caughtUp: false
+			};
+		}
+		if (answer.next === void 0) return {
+			taken,
+			history_id: answer.historyId,
+			offset: 0,
+			caughtUp: true
+		};
+		page = answer.next;
+	}
+	return {
+		taken,
+		history_id: before,
+		offset: skip,
+		caughtUp: false
+	};
+};
+//#endregion
+export { walkHistory };

package/dist/gmail/index.d.ts

@@ -0,0 +1,4 @@
+import { gmailApiUrl, gmailPlugin } from "./plugin.js";
+import { mailsPerPoll } from "./new-mail.js";
+import { MailAddress, MailAttachment, MailItem } from "./item-bounds.js";
+export { type MailAddress, type MailAttachment, type MailItem, gmailApiUrl, gmailPlugin, mailsPerPoll };

package/dist/gmail/index.js

@@ -0,0 +1,3 @@
+import { mailsPerPoll } from "./new-mail.js";
+import { gmailApiUrl, gmailPlugin } from "./plugin.js";
+export { gmailApiUrl, gmailPlugin, mailsPerPoll };

package/dist/gmail/item-bounds.d.ts

@@ -0,0 +1,26 @@
+//#region src/gmail/item-bounds.d.ts
+/** An address of a mail as a run gets it: the display name and address as the mail states them, `null` when it states none. */
+export type MailAddress = {
+  name: string | null;
+  address: string | null;
+};
+export type MailAttachment = {
+  filename: string | null;
+  content_type: string | null;
+  size: number;
+};
+/** One new mail as a run's input. `truncated` is set when a value was cut short or left out to fit the bounds below. */
+export type MailItem = {
+  message_id: string;
+  thread_id: string;
+  from: MailAddress | null;
+  to: MailAddress[];
+  cc: MailAddress[];
+  subject: string | null;
+  date: string | null;
+  text: string | null;
+  html: string | null;
+  attachments: MailAttachment[] | null;
+  truncated: boolean;
+};
+//#endregion

package/dist/gmail/item-bounds.js

@@ -0,0 +1,76 @@
+//#region src/gmail/item-bounds.ts
+/** The most of each value a run gets of one mail, so a mail cannot make a poll's item too large to start a run. */
+const bounds = {
+	addressLength: 320,
+	nameLength: 320,
+	addresses: 50,
+	subjectLength: 1e3,
+	dateLength: 100,
+	/** Characters of `text` and of `html` each; as JSON, at most six bytes a character. */
+	bodyLength: 131072,
+	attachments: 50,
+	filenameLength: 255,
+	contentTypeLength: 255,
+	/** The most one item is as JSON, below a run's input limit of 1 MiB: past it, `html` is left out, then `text`. */
+	itemBytes: 786432
+};
+const jsonBytes = (value) => new TextEncoder().encode(JSON.stringify(value)).length;
+const unstorable = /\u0000|[\uD800-\uDBFF](?![\uDC00-\uDFFF])|(?<![\uD800-\uDBFF])[\uDC00-\uDFFF]/g;
+/**
+* Leaves out of each value what the database cannot store and cuts it to its bound, never between the halves of a
+* surrogate pair, then leaves out `html` and then `text` while the item is over `itemBytes` as JSON. Every other value
+* together stays under it even when each character is escaped, so the result always fits.
+*/
+const boundItem = (item) => {
+	let truncated = item.truncated;
+	const cut = (value, most) => {
+		if (value === null) return value;
+		const storable = value.replace(unstorable, "");
+		if (storable.length !== value.length) truncated = true;
+		if (storable.length <= most) return storable;
+		truncated = true;
+		const splitsPair = /[\uD800-\uDBFF]/.test(storable.charAt(most - 1));
+		return storable.slice(0, splitsPair ? most - 1 : most);
+	};
+	const few = (list, most) => {
+		if (list.length <= most) return list;
+		truncated = true;
+		return list.slice(0, most);
+	};
+	const address = ({ name, address }) => ({
+		name: cut(name, bounds.nameLength),
+		address: cut(address, bounds.addressLength)
+	});
+	const bounded = {
+		message_id: item.message_id,
+		thread_id: item.thread_id,
+		from: item.from && address(item.from),
+		to: few(item.to, bounds.addresses).map(address),
+		cc: few(item.cc, bounds.addresses).map(address),
+		subject: cut(item.subject, bounds.subjectLength),
+		date: cut(item.date, bounds.dateLength),
+		text: cut(item.text, bounds.bodyLength),
+		html: cut(item.html, bounds.bodyLength),
+		attachments: item.attachments && few(item.attachments, bounds.attachments).map(({ filename, content_type, size }) => ({
+			filename: cut(filename, bounds.filenameLength),
+			content_type: cut(content_type, bounds.contentTypeLength),
+			size
+		})),
+		truncated: false
+	};
+	for (const field of ["html", "text"]) {
+		if (jsonBytes({
+			...bounded,
+			truncated
+		}) <= bounds.itemBytes) break;
+		if (bounded[field] === null) continue;
+		bounded[field] = null;
+		truncated = true;
+	}
+	return {
+		...bounded,
+		truncated
+	};
+};
+//#endregion
+export { boundItem, bounds };

package/dist/gmail/mail-item.js

@@ -0,0 +1,69 @@
+import PostalMime, { addressParser, decodeWords } from "postal-mime";
+//#region src/gmail/mail-item.ts
+const tooComplex = /* @__PURE__ */ new Set([
+	"EMAXNESTINGDEPTH",
+	"EMAXHEADERSIZE",
+	"EMAXPARTCOUNT",
+	"EMAXFORWARDEDADDRESSES"
+]);
+const stated = (value) => value === void 0 || value === "" ? null : value;
+const mailboxes = (list) => (list ?? []).flatMap((entry) => entry.group ? entry.group : [entry]).map(({ name, address }) => ({
+	name: stated(name),
+	address: stated(address)
+}));
+/** A mail's raw source as the run's input, values as the mail states them; `undefined` when it is too complex to parse. */
+const parsedItem = async (ref, raw) => {
+	const mail = await PostalMime.parse(raw).catch((error) => {
+		if (tooComplex.has(error?.code ?? "")) return;
+		throw error;
+	});
+	if (!mail) return;
+	return {
+		message_id: ref.id,
+		thread_id: ref.threadId,
+		from: mailboxes(mail.from ? [mail.from] : void 0)[0] ?? null,
+		to: mailboxes(mail.to),
+		cc: mailboxes(mail.cc),
+		subject: stated(mail.subject),
+		date: stated(mail.date),
+		text: stated(mail.text),
+		html: stated(mail.html),
+		attachments: mail.attachments.map((attachment) => ({
+			filename: attachment.filename,
+			content_type: stated(attachment.mimeType),
+			size: attachmentSize(attachment.content)
+		})),
+		truncated: false
+	};
+};
+const attachmentSize = (content) => typeof content === "string" ? content.length : content.byteLength;
+/**
+* A mail too large or too complex to read whole, from its headers alone: no body and no attachment names, which the
+* headers do not hold, and `truncated` set.
+*/
+const headersItem = (ref, headers) => {
+	const header = (name) => headers.find((entry) => entry.name.toLowerCase() === name.toLowerCase())?.value;
+	const addresses = (name) => {
+		const value = header(name);
+		return value === void 0 ? [] : mailboxes(addressParser(value)).map(({ name: shown, address }) => ({
+			name: shown === null ? null : stated(decodeWords(shown)),
+			address
+		}));
+	};
+	const subject = header("Subject");
+	return {
+		message_id: ref.id,
+		thread_id: ref.threadId,
+		from: addresses("From")[0] ?? null,
+		to: addresses("To"),
+		cc: addresses("Cc"),
+		subject: subject === void 0 ? null : stated(decodeWords(subject)),
+		date: stated(header("Date")),
+		text: null,
+		html: null,
+		attachments: null,
+		truncated: true
+	};
+};
+//#endregion
+export { headersItem, parsedItem };

package/dist/gmail/new-mail.d.ts

@@ -0,0 +1,5 @@
+import "@protobase/workflows/plugin";
+//#region src/gmail/new-mail.d.ts
+/** The most mails one poll reads: 90 raw reads and a history call stay within a mailbox's quota for one minute. */
+export declare const mailsPerPoll = 90;
+//#endregion

package/dist/gmail/new-mail.js

@@ -0,0 +1,161 @@
+import { GmailNotFound, gmailApi } from "./api.js";
+import { historyPage, labels, messagesPage, profile } from "./calls.js";
+import { labelId, readCursor } from "./cursor.js";
+import { passes } from "./filters.js";
+import { walkHistory } from "./history-walk.js";
+import { boundItem } from "./item-bounds.js";
+import { readMessage } from "./read-message.js";
+//#region src/gmail/new-mail.ts
+/** The most mails one poll reads: 90 raw reads and a history call stay within a mailbox's quota for one minute. */
+const mailsPerPoll = 90;
+const filterText = {
+	type: "string",
+	minLength: 1,
+	maxLength: 500
+};
+const seconds = (time) => Math.floor(time.getTime() / 1e3);
+const findLabel = async (api, wanted) => {
+	const label = (await labels(api)).find(({ id, name }) => id === wanted || name === wanted);
+	if (!label) throw new Error(`The mailbox has no label "${wanted}"`);
+	if (!labelId.test(label.id)) throw new Error("Gmail labels.list answered an unexpected shape");
+	return label.id;
+};
+const filtersOf = (input) => ({
+	...typeof input.from === "string" && { from: input.from },
+	...typeof input.to === "string" && { to: input.to },
+	...typeof input.subject === "string" && { subject: input.subject }
+});
+const itemsOf = async (api, taken, filters) => {
+	const items = [];
+	const seen = /* @__PURE__ */ new Set();
+	for (const ref of taken) {
+		if (seen.has(ref.id)) continue;
+		seen.add(ref.id);
+		const item = await readMessage(api, ref);
+		if (item && passes(item, filters)) items.push({
+			key: ref.id,
+			data: boundItem(item)
+		});
+	}
+	return items;
+};
+const historyPoll = async (api, cursor, filters, limit, due) => {
+	const read = (page) => historyPage(api, {
+		start: cursor.history_id,
+		label: cursor.label_id,
+		page
+	});
+	const walked = await walkHistory(read, cursor.history_id, cursor.offset, limit).catch((error) => {
+		if (error instanceof GmailNotFound) return;
+		throw error;
+	});
+	if (!walked) return {
+		items: [],
+		cursor: {
+			label_id: cursor.label_id,
+			polled_at: cursor.polled_at,
+			recovery: {
+				since: cursor.polled_at,
+				page_token: null,
+				resume_history_id: await profile(api)
+			}
+		}
+	};
+	const next = {
+		label_id: cursor.label_id,
+		history_id: walked.history_id,
+		offset: walked.offset,
+		polled_at: walked.caughtUp ? seconds(due) : cursor.polled_at
+	};
+	return {
+		items: await itemsOf(api, walked.taken, filters),
+		cursor: next
+	};
+};
+const recoveryPoll = async (api, cursor, filters, limit) => {
+	const { since, page_token: page, resume_history_id: resume } = cursor.recovery;
+	const listed = await messagesPage(api, {
+		label: cursor.label_id,
+		since,
+		page: page ?? void 0,
+		limit
+	});
+	return {
+		items: await itemsOf(api, listed.messages.slice(0, limit), filters),
+		cursor: listed.next ? {
+			...cursor,
+			recovery: {
+				...cursor.recovery,
+				page_token: listed.next
+			}
+		} : {
+			label_id: cursor.label_id,
+			history_id: resume,
+			offset: 0,
+			polled_at: cursor.polled_at
+		}
+	};
+};
+const api = (origin, { fetch, connection, signal }) => gmailApi({
+	origin,
+	fetch,
+	connection,
+	signal
+});
+/**
+* `gmail:new_mail`: one run per new mail on a label of the connected mailbox, from the time the trigger is turned on,
+* read with read-only access by polling the mailbox's history every minute. Google answers at `origin`.
+*/
+const newMailTrigger = (origin) => ({
+	kind: "polling",
+	label: "New mail",
+	description: "Starts one run for each new mail on a label of a connected mailbox, INBOX by default, that passes the filters set.",
+	connection: "google",
+	input: {
+		type: "object",
+		additionalProperties: false,
+		properties: {
+			label: {
+				type: "string",
+				minLength: 1,
+				maxLength: 225,
+				description: "the label to watch, by name or id; default INBOX"
+			},
+			from: {
+				...filterText,
+				description: "only mail whose sender's name or address contains this, in any case"
+			},
+			to: {
+				...filterText,
+				description: "only mail with a To or Cc recipient whose name or address contains this, in any case"
+			},
+			subject: {
+				...filterText,
+				description: "only mail whose subject contains this, in any case"
+			}
+		}
+	},
+	output: {
+		type: "object",
+		description: "{ message_id, thread_id, from, to, cc, subject, date, text, html, attachments: [{ filename, content_type, size }], truncated }"
+	},
+	every: "1 minute",
+	limit: 90,
+	start: async (context) => {
+		const gmail = api(origin, context);
+		return {
+			label_id: await findLabel(gmail, typeof context.input.label === "string" ? context.input.label : "INBOX"),
+			history_id: await profile(gmail),
+			offset: 0,
+			polled_at: seconds(/* @__PURE__ */ new Date())
+		};
+	},
+	poll: async (context) => {
+		const gmail = api(origin, context);
+		const cursor = readCursor(context.cursor);
+		const filters = filtersOf(context.input);
+		return "recovery" in cursor ? recoveryPoll(gmail, cursor, filters, context.limit) : historyPoll(gmail, cursor, filters, context.limit, context.due);
+	}
+});
+//#endregion
+export { mailsPerPoll, newMailTrigger };

package/dist/gmail/plugin.d.ts

@@ -0,0 +1,29 @@
+//#region src/gmail/plugin.d.ts
+/** Where Gmail's API answers. */
+export declare const gmailApiUrl = "https://gmail.googleapis.com";
+/**
+ * `gmail:*`: new mail of a mailbox its owner connected through the app's Google sign-in, with read-only access. Only
+ * the app's code passes `apiUrl`, such as a test's own Gmail; a workflow never sets where the token goes.
+ */
+export declare const gmailPlugin: ({ apiUrl }?: {
+  apiUrl?: string;
+}) => {
+  readonly name: "gmail";
+  readonly label: "Gmail";
+  readonly connections: {
+    readonly google: {
+      readonly label: "Google account";
+      readonly signIn: "google";
+      readonly scopes: ["https://www.googleapis.com/auth/gmail.readonly"];
+      readonly link_params: {
+        readonly access_type: "offline";
+        readonly prompt: "consent";
+      };
+      readonly revocation_url: "https://oauth2.googleapis.com/revoke";
+    };
+  };
+  readonly triggers: {
+    readonly new_mail: import("@protobase/workflows/plugin").PollingTrigger;
+  };
+};
+//#endregion

package/dist/gmail/plugin.js

@@ -0,0 +1,36 @@
+import { newMailTrigger } from "./new-mail.js";
+import { definePlugin } from "@protobase/workflows/plugin";
+//#region src/gmail/plugin.ts
+/** Where Gmail's API answers. */
+const gmailApiUrl = "https://gmail.googleapis.com";
+const localHosts = [
+	"localhost",
+	"127.0.0.1",
+	"[::1]"
+];
+const apiOrigin = (value) => {
+	const url = URL.canParse(value) ? new URL(value) : void 0;
+	if (!url || !(url.protocol === "https:" || url.protocol === "http:" && localHosts.includes(url.hostname))) throw new Error(`The Gmail plugin's apiUrl must be an https URL: ${value}`);
+	return url.origin;
+};
+/**
+* `gmail:*`: new mail of a mailbox its owner connected through the app's Google sign-in, with read-only access. Only
+* the app's code passes `apiUrl`, such as a test's own Gmail; a workflow never sets where the token goes.
+*/
+const gmailPlugin = ({ apiUrl = gmailApiUrl } = {}) => definePlugin({
+	name: "gmail",
+	label: "Gmail",
+	connections: { google: {
+		label: "Google account",
+		signIn: "google",
+		scopes: ["https://www.googleapis.com/auth/gmail.readonly"],
+		link_params: {
+			access_type: "offline",
+			prompt: "consent"
+		},
+		revocation_url: "https://oauth2.googleapis.com/revoke"
+	} },
+	triggers: { new_mail: newMailTrigger(apiOrigin(apiUrl)) }
+});
+//#endregion
+export { gmailApiUrl, gmailPlugin };

package/dist/gmail/read-message.js

@@ -0,0 +1,28 @@
+import { GmailNotFound } from "./api.js";
+import { messageHeaders, rawMessage } from "./calls.js";
+import { headersItem, parsedItem } from "./mail-item.js";
+import { ResponseTooLargeError, fetchMaxBytes } from "@protobase/workflows/plugin";
+//#region src/gmail/read-message.ts
+const unlessDeleted = (read) => read.catch((error) => {
+	if (error instanceof GmailNotFound) return;
+	throw error;
+});
+const rawOrTooLarge = (api, id) => rawMessage(api, id, fetchMaxBytes).catch((error) => {
+	if (error instanceof ResponseTooLargeError) return "too large";
+	throw error;
+});
+/**
+* One message as a run's input: read whole, at most 10 MiB of answer, which holds the mail in base64 and so about
+* 7.5 MiB of mail, else from its headers alone when it is larger or too complex to parse; `undefined` when it was
+* deleted since it was listed.
+*/
+const readMessage = async (api, ref) => {
+	const raw = await unlessDeleted(rawOrTooLarge(api, ref.id));
+	if (raw === void 0) return;
+	const parsed = raw === "too large" ? void 0 : await parsedItem(ref, raw);
+	if (parsed) return parsed;
+	const headers = await unlessDeleted(messageHeaders(api, ref.id));
+	return headers && headersItem(ref, headers);
+};
+//#endregion
+export { readMessage };

package/dist/index.d.ts

@@ -1,2 +1,4 @@
+import { gmailPlugin } from "./gmail/plugin.js";
+import "./gmail/index.js";
 import { appPlugin } from "./app.js";
-export { appPlugin, appPlugin as default };
+export { appPlugin, appPlugin as default, gmailPlugin };

package/dist/index.js

@@ -1,2 +1,3 @@
 import { appPlugin } from "./app.js";
-export { appPlugin, appPlugin as default };
+import { gmailPlugin } from "./gmail/plugin.js";
+export { appPlugin, appPlugin as default, gmailPlugin };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@protobase/workflow-plugins",
-  "version": "0.71.1",
+  "version": "0.71.3",
   "description": "The built-in workflow trigger and step types, written on the public plugin interface like any other plugin.",
   "license": "Apache-2.0",
   "repository": {
@@ -15,7 +15,8 @@
     "node": ">=22.12.0"
   },
   "exports": {
-    ".": "./dist/index.js"
+    ".": "./dist/index.js",
+    "./gmail": "./dist/gmail/index.js"
   },
   "types": "./dist/index.d.ts",
   "files": [
@@ -29,6 +30,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@protobase/workflows": "0.71.1"
+    "@protobase/workflows": "0.71.3",
+    "postal-mime": "^4.2.0"
   }
 }