@robinpath/gmail - npm Package Compare versions

Comparing version

0.1.1

0.3.0

+34

dist/gmail.d.ts

		/**
		* RobinPath Gmail Module (Node port)
		*
		* Gmail API v1 — list/search, send, trash/untrash/delete, label modify,
		* labels CRUD, threads, and drafts. Mirror of packages/php/gmail/src/index.php
		* for the WordPress plugin; shares the same credential contract, metadata
		* shape, and error taxonomy so the visual editor can render both identically.
		*
		* Authentication (two modes):
		*
		* 1. `access_token` (default, easiest) — the user pastes a short-lived OAuth2
		* access token obtained externally (e.g. Google's OAuth Playground). If
		* the credential also includes `refresh_token` + `client_id` +
		* `client_secret`, expired tokens are refreshed automatically and the
		* new `access_token` is written back into the vault.
		*
		* 2. `service_account` — Google Workspace Domain-Wide Delegation. Uses the
		* service-account JSON key to mint a JWT-bearer assertion and impersonate
		* `impersonated_user`. Requires Node's built-in `crypto` for RS256.
		*
		* Credential type declared by this module:
		* - gmail : { auth_mode, access_token?, refresh_token?, client_id?, client_secret?,
		* impersonated_user?, client_email?, private_key?, scopes? }
		*
		* API reference: https://developers.google.com/gmail/api/reference/rest
		* OAuth scopes: https://developers.google.com/gmail/api/auth/scopes
		*/
		import type { BuiltinHandler, CredentialTypeSchema, FunctionMetadata, ModuleHost, ModuleMetadata } from "@robinpath/core";
		export declare function configureGmail(h: ModuleHost): void;
		export declare const GmailFunctions: Record<string, BuiltinHandler>;
		export declare const GmailCredentialTypes: CredentialTypeSchema[];
		export declare const GmailFunctionMetadata: Record<string, FunctionMetadata>;
		export declare const GmailModuleMetadata: ModuleMetadata;
		//# sourceMappingURL=gmail.d.ts.map

+1

dist/gmail.d.ts.map

{"version":3,"file":"gmail.d.ts","sourceRoot":"","sources":["../src/gmail.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAKH,OAAO,KAAK,EACV,cAAc,EACd,oBAAoB,EACpB,gBAAgB,EAChB,UAAU,EACV,cAAc,EAEf,MAAM,iBAAiB,CAAC;AAezB,wBAAgB,cAAc,CAAC,CAAC,EAAE,UAAU,GAAG,IAAI,CAElD;AAw/BD,eAAO,MAAM,cAAc,EAAE,MAAM,CAAC,MAAM,EAAE,cAAc,CAsBzD,CAAC;AAQF,eAAO,MAAM,oBAAoB,EAAE,oBAAoB,EA0FtD,CAAC;AAiFF,eAAO,MAAM,qBAAqB,EAAE,MAAM,CAAC,MAAM,EAAE,gBAAgB,CAwgBlE,CAAC;AAIF,eAAO,MAAM,mBAAmB,EAAE,cAuCjC,CAAC"}

+1483

dist/gmail.js

		/**
		* RobinPath Gmail Module (Node port)
		*
		* Gmail API v1 — list/search, send, trash/untrash/delete, label modify,
		* labels CRUD, threads, and drafts. Mirror of packages/php/gmail/src/index.php
		* for the WordPress plugin; shares the same credential contract, metadata
		* shape, and error taxonomy so the visual editor can render both identically.
		*
		* Authentication (two modes):
		*
		* 1. `access_token` (default, easiest) — the user pastes a short-lived OAuth2
		* access token obtained externally (e.g. Google's OAuth Playground). If
		* the credential also includes `refresh_token` + `client_id` +
		* `client_secret`, expired tokens are refreshed automatically and the
		* new `access_token` is written back into the vault.
		*
		* 2. `service_account` — Google Workspace Domain-Wide Delegation. Uses the
		* service-account JSON key to mint a JWT-bearer assertion and impersonate
		* `impersonated_user`. Requires Node's built-in `crypto` for RS256.
		*
		* Credential type declared by this module:
		* - gmail : { auth_mode, access_token?, refresh_token?, client_id?, client_secret?,
		* impersonated_user?, client_email?, private_key?, scopes? }
		*
		* API reference: https://developers.google.com/gmail/api/reference/rest
		* OAuth scopes: https://developers.google.com/gmail/api/auth/scopes
		*/
		import { createSign } from "node:crypto";
		import { Buffer } from "node:buffer";
		// ── Module-local state (populated by configure hook) ────────────────────
		const state = {};
		function host() {
		if (!state.host) {
		throw new Error("Gmail module not initialized. Pass the adapter to rp.registerModule() via loadModule so its configure() hook runs first.");
		}
		return state.host;
		}
		export function configureGmail(h) {
		state.host = h;
		}
		// ── Constants ──────────────────────────────────────────────────────────
		const TOKEN_URL = "https://oauth2.googleapis.com/token";
		const GMAIL_API = "https://gmail.googleapis.com/gmail/v1/users/";
		const DEFAULT_SCOPE = "https://www.googleapis.com/auth/gmail.modify";
		const DEFAULT_USER = "me";
		const CREDENTIAL_TYPE = "gmail";
		const tokenCache = new Map();
		const TOKEN_TTL_MS = 50 * 60 * 1000; // 50 minutes — same as the PHP TOKEN_TTL.
		function cacheGet(key) {
		const entry = tokenCache.get(key);
		if (!entry)
		return null;
		if (entry.expiresAt <= Date.now()) {
		tokenCache.delete(key);
		return null;
		}
		return entry.token;
		}
		function cacheSet(key, token) {
		tokenCache.set(key, { token, expiresAt: Date.now() + TOKEN_TTL_MS });
		}
		function cacheDelete(key) {
		tokenCache.delete(key);
		}
		function errorReturn(error, code, extra = {}) {
		return { error, code, ...extra };
		}
		function isErrorReturn(v) {
		return !!v && typeof v === "object" && "error" in v && "code" in v;
		}
		async function resolveCredential(credentialSlug) {
		if (!credentialSlug) {
		return errorReturn("Credential slug is required.", "credential_not_found");
		}
		let fields;
		try {
		fields = await host().credentials.get(credentialSlug);
		}
		catch (e) {
		return errorReturn(e instanceof Error ? e.message : String(e), "credential_not_found");
		}
		if (!fields) {
		return errorReturn(`Credential '${credentialSlug}' not found.`, "credential_not_found");
		}
		const mode = String(fields.auth_mode ?? "access_token");
		if (mode === "service_account") {
		return resolveServiceAccountToken(credentialSlug, fields);
		}
		return resolveAccessToken(credentialSlug, fields);
		}
		async function resolveAccessToken(credentialSlug, fields) {
		const token = String(fields.access_token ?? "");
		const refreshToken = String(fields.refresh_token ?? "");
		const clientId = String(fields.client_id ?? "");
		const clientSecret = String(fields.client_secret ?? "");
		const refreshCacheKey = refreshToken && clientId && clientSecret
		? `refresh\|${credentialSlug}\|${refreshToken}`
		: undefined;
		// Prefer a cached refreshed token if one exists.
		if (refreshCacheKey) {
		const cached = cacheGet(refreshCacheKey);
		if (cached) {
		return {
		token: cached,
		user: DEFAULT_USER,
		refreshCacheKey,
		fromRefresh: true,
		credentialSlug,
		fields,
		mode: "access_token",
		};
		}
		}
		if (token) {
		return {
		token,
		user: DEFAULT_USER,
		refreshCacheKey,
		fromRefresh: false,
		credentialSlug,
		fields,
		mode: "access_token",
		};
		}
		// No static token; try a refresh.
		if (!refreshToken \|\| !clientId \|\| !clientSecret) {
		return errorReturn("Credential has no `access_token`, and not enough info to refresh (need refresh_token + client_id + client_secret).", "token_missing");
		}
		const refreshed = await refreshAccessToken(credentialSlug, refreshToken, clientId, clientSecret);
		if (isErrorReturn(refreshed))
		return refreshed;
		// Persist the new access_token back into the credential so subsequent calls
		// pick it up even after a process restart clears `tokenCache`.
		await writeBackAccessToken(credentialSlug, fields, refreshed.token);
		return {
		token: refreshed.token,
		user: DEFAULT_USER,
		refreshCacheKey,
		fromRefresh: true,
		credentialSlug,
		fields: { ...fields, access_token: refreshed.token },
		mode: "access_token",
		};
		}
		async function refreshAccessToken(credentialSlug, refreshToken, clientId, clientSecret) {
		const body = new URLSearchParams({
		grant_type: "refresh_token",
		refresh_token: refreshToken,
		client_id: clientId,
		client_secret: clientSecret,
		}).toString();
		let response;
		try {
		response = await fetch(TOKEN_URL, {
		method: "POST",
		headers: { "Content-Type": "application/x-www-form-urlencoded" },
		body,
		});
		}
		catch (e) {
		return errorReturn(e instanceof Error ? e.message : String(e), "transport");
		}
		const raw = await response.text();
		let decoded = {};
		try {
		decoded = raw ? JSON.parse(raw) : {};
		}
		catch {
		decoded = {};
		}
		const status = response.status;
		const accessToken = String(decoded.access_token ?? "");
		if (status < 200 \|\| status >= 300 \|\| !accessToken) {
		const msg = String(decoded.error_description ?? decoded.error ?? "Refresh failed.");
		return errorReturn(msg, "token_exchange_failed", { status });
		}
		const cacheKey = `refresh\|${credentialSlug}\|${refreshToken}`;
		cacheSet(cacheKey, accessToken);
		return { token: accessToken };
		}
		async function writeBackAccessToken(slug, fields, newToken) {
		try {
		await host().credentials.set(slug, CREDENTIAL_TYPE, {
		...fields,
		access_token: newToken,
		});
		}
		catch {
		// Best-effort — in-memory cache still has the fresh token.
		}
		}
		async function resolveServiceAccountToken(credentialSlug, fields) {
		const email = String(fields.client_email ?? "");
		const key = String(fields.private_key ?? "");
		const scope = String(fields.scopes ?? DEFAULT_SCOPE);
		const sub = String(fields.impersonated_user ?? "");
		if (!email \|\| !key) {
		return errorReturn("Service-account credential missing `client_email` or `private_key`.", "private_key_missing");
		}
		if (!sub) {
		return errorReturn("`impersonated_user` is required for service-account mode (Workspace user whose mailbox to access).", "token_missing");
		}
		const cacheKey = `sa\|${email}\|${sub}\|${scope}`;
		const cached = cacheGet(cacheKey);
		if (cached) {
		return {
		token: cached,
		user: sub,
		credentialSlug,
		fields,
		mode: "service_account",
		fromRefresh: true,
		};
		}
		const jwt = buildJwt(email, key, scope, sub);
		if (isErrorReturn(jwt))
		return jwt;
		const body = new URLSearchParams({
		grant_type: "urn:ietf:params:oauth:grant-type:jwt-bearer",
		assertion: jwt,
		}).toString();
		let response;
		try {
		response = await fetch(TOKEN_URL, {
		method: "POST",
		headers: { "Content-Type": "application/x-www-form-urlencoded" },
		body,
		});
		}
		catch (e) {
		return errorReturn(e instanceof Error ? e.message : String(e), "transport");
		}
		const raw = await response.text();
		let decoded = {};
		try {
		decoded = raw ? JSON.parse(raw) : {};
		}
		catch {
		decoded = {};
		}
		const status = response.status;
		const accessToken = String(decoded.access_token ?? "");
		if (status < 200 \|\| status >= 300 \|\| !accessToken) {
		const msg = String(decoded.error_description ?? decoded.error ?? "Token exchange failed.");
		return errorReturn(msg, "token_exchange_failed", { status });
		}
		cacheSet(cacheKey, accessToken);
		return {
		token: accessToken,
		user: sub,
		credentialSlug,
		fields,
		mode: "service_account",
		fromRefresh: true,
		};
		}
		function buildJwt(email, privateKey, scope, subject) {
		const now = Math.floor(Date.now() / 1000);
		const header = { alg: "RS256", typ: "JWT" };
		const payload = {
		iss: email,
		sub: subject,
		scope,
		aud: TOKEN_URL,
		exp: now + 3600,
		iat: now,
		};
		const h = b64url(Buffer.from(JSON.stringify(header), "utf8"));
		const p = b64url(Buffer.from(JSON.stringify(payload), "utf8"));
		const signingInput = `${h}.${p}`;
		try {
		const signer = createSign("RSA-SHA256");
		signer.update(signingInput);
		signer.end();
		const signature = signer.sign(privateKey);
		return `${signingInput}.${b64url(signature)}`;
		}
		catch (e) {
		return errorReturn(`Could not sign JWT: ${e instanceof Error ? e.message : String(e)}`, "jwt_sign_failed");
		}
		}
		function b64url(data) {
		const buf = typeof data === "string" ? Buffer.from(data, "utf8") : data;
		return buf
		.toString("base64")
		.replace(/\+/g, "-")
		.replace(/\//g, "_")
		.replace(/=+$/g, "");
		}
		// ── HTTP — Gmail API ───────────────────────────────────────────────────
		async function call(cred, method, path, body) {
		const resolved = await resolveCredential(cred);
		if (isErrorReturn(resolved))
		return resolved;
		const first = await callWithToken(resolved, method, path, body);
		if (isErrorReturn(first) &&
		first.status === 401 &&
		resolved.mode === "access_token") {
		// Try one refresh + retry (only if the credential has a refresh setup).
		const refreshToken = String(resolved.fields.refresh_token ?? "");
		const clientId = String(resolved.fields.client_id ?? "");
		const clientSecret = String(resolved.fields.client_secret ?? "");
		if (refreshToken && clientId && clientSecret) {
		if (resolved.refreshCacheKey)
		cacheDelete(resolved.refreshCacheKey);
		const refreshed = await refreshAccessToken(resolved.credentialSlug, refreshToken, clientId, clientSecret);
		if (!isErrorReturn(refreshed)) {
		await writeBackAccessToken(resolved.credentialSlug, resolved.fields, refreshed.token);
		const retried = await callWithToken({
		...resolved,
		token: refreshed.token,
		fromRefresh: true,
		fields: { ...resolved.fields, access_token: refreshed.token },
		}, method, path, body);
		return retried;
		}
		}
		}
		return first;
		}
		async function callWithToken(resolved, method, path, body) {
		const url = GMAIL_API +
		encodeURIComponent(resolved.user \|\| DEFAULT_USER) +
		"/" +
		path.replace(/^\/+/, "");
		const init = {
		method,
		headers: {
		Authorization: `Bearer ${resolved.token}`,
		"Content-Type": "application/json",
		},
		};
		if (body !== null && body !== undefined) {
		init.body = JSON.stringify(body);
		}
		let response;
		try {
		response = await fetch(url, init);
		}
		catch (e) {
		return errorReturn(e instanceof Error ? e.message : String(e), "transport");
		}
		const status = response.status;
		const rawBody = await response.text();
		let decoded;
		try {
		decoded = rawBody ? JSON.parse(rawBody) : null;
		}
		catch {
		decoded = { raw: rawBody };
		}
		if (status >= 200 && status < 300) {
		if (rawBody === "") {
		return { ok: true, status };
		}
		if (decoded && typeof decoded === "object")
		return decoded;
		return { raw: rawBody };
		}
		const errObj = decoded && typeof decoded === "object" && "error" in decoded
		? decoded.error
		: null;
		let message = `Gmail API returned HTTP ${status}.`;
		if (errObj && typeof errObj === "object" && "message" in errObj) {
		message = String(errObj.message);
		}
		else if (typeof errObj === "string") {
		message = errObj;
		}
		let code = "gmail_error";
		if (status === 429) {
		code = "rate_limited";
		}
		else if (status === 404) {
		code = "not_found";
		}
		else if (status === 403) {
		let reason = "";
		if (errObj && typeof errObj === "object" && "errors" in errObj) {
		const errs = errObj.errors;
		if (Array.isArray(errs) && errs.length > 0) {
		const e0 = errs[0];
		reason = String(e0?.reason ?? "");
		}
		}
		if (reason === "dailyLimitExceeded" \|\|
		reason === "userRateLimitExceeded" \|\|
		reason === "quotaExceeded") {
		code = "quota_exceeded";
		}
		else {
		code = "permission_denied";
		}
		}
		else if (status === 401) {
		code = "permission_denied";
		}
		return errorReturn(message, code, {
		status,
		gmail_error: decoded && typeof decoded === "object" ? decoded : { raw: rawBody },
		});
		}
		// ── Query-string builders (mirror PHP) ─────────────────────────────────
		function buildMessagesQuery(opts) {
		const params = [];
		if (opts.q) {
		params.push(`q=${encodeURIComponent(String(opts.q))}`);
		}
		if (opts.maxResults !== undefined) {
		params.push(`maxResults=${encodeURIComponent(String(Number(opts.maxResults) \| 0))}`);
		}
		if (opts.pageToken !== undefined) {
		params.push(`pageToken=${encodeURIComponent(String(opts.pageToken))}`);
		}
		if (opts.includeSpamTrash) {
		params.push(`includeSpamTrash=true`);
		}
		if (Array.isArray(opts.labelIds)) {
		for (const lid of opts.labelIds) {
		params.push(`labelIds=${encodeURIComponent(String(lid))}`);
		}
		}
		return params.length ? `?${params.join("&")}` : "";
		}
		function buildGetMessageQuery(opts) {
		const params = [];
		if (opts.format) {
		params.push(`format=${encodeURIComponent(String(opts.format))}`);
		}
		if (Array.isArray(opts.metadataHeaders)) {
		for (const h of opts.metadataHeaders) {
		params.push(`metadataHeaders=${encodeURIComponent(String(h))}`);
		}
		}
		return params.length ? `?${params.join("&")}` : "";
		}
		function buildDraftsQuery(opts) {
		const params = [];
		if (opts.q) {
		params.push(`q=${encodeURIComponent(String(opts.q))}`);
		}
		if (opts.maxResults !== undefined) {
		params.push(`maxResults=${encodeURIComponent(String(Number(opts.maxResults) \| 0))}`);
		}
		if (opts.pageToken !== undefined) {
		params.push(`pageToken=${encodeURIComponent(String(opts.pageToken))}`);
		}
		return params.length ? `?${params.join("&")}` : "";
		}
		function buildRawMessage(fields) {
		if (!fields.to) {
		return errorReturn("`to` is required.", "fields_missing");
		}
		if (!fields.subject) {
		return errorReturn("`subject` is required.", "fields_missing");
		}
		const hasText = !!fields.text;
		const hasHtml = !!fields.html;
		if (!hasText && !hasHtml) {
		return errorReturn("At least one of `text` or `html` is required.", "fields_missing");
		}
		const crlf = "\r\n";
		const headers = [];
		headers.push("MIME-Version: 1.0");
		if (fields.from) {
		headers.push("From: " + encodeHeaderValue(stringifyAddressList(fields.from)));
		}
		headers.push("To: " + encodeHeaderValue(stringifyAddressList(fields.to)));
		if (fields.cc) {
		headers.push("Cc: " + encodeHeaderValue(stringifyAddressList(fields.cc)));
		}
		if (fields.bcc) {
		headers.push("Bcc: " + encodeHeaderValue(stringifyAddressList(fields.bcc)));
		}
		if (fields.replyTo) {
		headers.push("Reply-To: " + encodeHeaderValue(stringifyAddressList(fields.replyTo)));
		}
		headers.push("Subject: " + encodeHeaderValue(String(fields.subject)));
		if (fields.inReplyTo) {
		const msgId = "<" + String(fields.inReplyTo).replace(/^<\|>$/g, "") + ">";
		headers.push("In-Reply-To: " + msgId);
		headers.push("References: " + msgId);
		}
		if (fields.headers && typeof fields.headers === "object" && !Array.isArray(fields.headers)) {
		const reserved = new Set([
		"content-type",
		"mime-version",
		"from",
		"to",
		"cc",
		"bcc",
		"subject",
		"reply-to",
		"in-reply-to",
		"references",
		]);
		for (const [name, value] of Object.entries(fields.headers)) {
		if (!name \|\| value === null \|\| value === undefined)
		continue;
		if (reserved.has(name.toLowerCase()))
		continue;
		headers.push(`${name}: ${encodeHeaderValue(String(value))}`);
		}
		}
		let body;
		if (hasText && hasHtml) {
		const boundary = "=_rp_" + randomHex(8);
		headers.push(`Content-Type: multipart/alternative; boundary="${boundary}"`);
		body =
		headers.join(crlf) +
		crlf +
		crlf +
		"This is a multi-part message in MIME format." +
		crlf +
		crlf +
		"--" +
		boundary +
		crlf +
		"Content-Type: text/plain; charset=UTF-8" +
		crlf +
		"Content-Transfer-Encoding: base64" +
		crlf +
		crlf +
		chunkSplit(Buffer.from(String(fields.text), "utf8").toString("base64"), 76, crlf) +
		"--" +
		boundary +
		crlf +
		"Content-Type: text/html; charset=UTF-8" +
		crlf +
		"Content-Transfer-Encoding: base64" +
		crlf +
		crlf +
		chunkSplit(Buffer.from(String(fields.html), "utf8").toString("base64"), 76, crlf) +
		"--" +
		boundary +
		"--" +
		crlf;
		}
		else if (hasHtml) {
		headers.push("Content-Type: text/html; charset=UTF-8");
		headers.push("Content-Transfer-Encoding: base64");
		body =
		headers.join(crlf) +
		crlf +
		crlf +
		chunkSplit(Buffer.from(String(fields.html), "utf8").toString("base64"), 76, crlf);
		}
		else {
		headers.push("Content-Type: text/plain; charset=UTF-8");
		headers.push("Content-Transfer-Encoding: base64");
		body =
		headers.join(crlf) +
		crlf +
		crlf +
		chunkSplit(Buffer.from(String(fields.text), "utf8").toString("base64"), 76, crlf);
		}
		return { raw: b64url(Buffer.from(body, "utf8")) };
		}
		function stringifyAddressList(value) {
		if (typeof value === "string")
		return value;
		if (value && typeof value === "object") {
		const obj = value;
		// Single {email, name}
		if (typeof obj.email === "string") {
		return formatAddress(String(obj.email), obj.name !== undefined ? String(obj.name) : null);
		}
		if (Array.isArray(value)) {
		const parts = [];
		for (const item of value) {
		if (typeof item === "string") {
		parts.push(item);
		}
		else if (item && typeof item === "object" && typeof item.email === "string") {
		const o = item;
		parts.push(formatAddress(String(o.email), o.name !== undefined ? String(o.name) : null));
		}
		}
		return parts.join(", ");
		}
		}
		return "";
		}
		function formatAddress(email, name) {
		if (name === null \|\| name === "")
		return email;
		// Non-ASCII → RFC 2047 B-encoded word.
		if (/[^\x20-\x7E]/.test(name)) {
		return ("=?UTF-8?B?" +
		Buffer.from(name, "utf8").toString("base64") +
		"?= <" +
		email +
		">");
		}
		let displayName = name;
		if (/[,"<>@]/.test(displayName)) {
		displayName = '"' + displayName.replace(/"/g, '\\"') + '"';
		}
		return displayName + " <" + email + ">";
		}
		function encodeHeaderValue(value) {
		if (/[^\x20-\x7E]/.test(value)) {
		return "=?UTF-8?B?" + Buffer.from(value, "utf8").toString("base64") + "?=";
		}
		return value;
		}
		function randomHex(bytes) {
		// Non-crypto random is fine for MIME boundary uniqueness.
		let out = "";
		for (let i = 0; i < bytes; i++) {
		const b = Math.floor(Math.random() * 256);
		out += b.toString(16).padStart(2, "0");
		}
		return out;
		}
		function chunkSplit(s, length, separator) {
		let out = "";
		for (let i = 0; i < s.length; i += length) {
		out += s.slice(i, i + length) + separator;
		}
		return out;
		}
		// ── Handlers — Messages ────────────────────────────────────────────────
		const listMessages = async (args) => {
		const cred = String(args[0] ?? "");
		const opts = args[1] && typeof args[1] === "object" && !Array.isArray(args[1])
		? args[1]
		: {};
		const path = "messages" + buildMessagesQuery(opts);
		return (await call(cred, "GET", path, null));
		};
		const getMessage = async (args) => {
		const cred = String(args[0] ?? "");
		const id = String(args[1] ?? "");
		const opts = args[2] && typeof args[2] === "object" && !Array.isArray(args[2])
		? args[2]
		: {};
		if (!id) {
		return errorReturn("messageId is required.", "fields_missing");
		}
		const path = "messages/" + encodeURIComponent(id) + buildGetMessageQuery(opts);
		return (await call(cred, "GET", path, null));
		};
		const sendMessage = async (args) => {
		const cred = String(args[0] ?? "");
		const fields = args[1] && typeof args[1] === "object" && !Array.isArray(args[1])
		? args[1]
		: {};
		const raw = buildRawMessage(fields);
		if (isErrorReturn(raw))
		return raw;
		const body = { raw: raw.raw };
		if (fields.threadId)
		body.threadId = String(fields.threadId);
		return (await call(cred, "POST", "messages/send", body));
		};
		const trashMessage = async (args) => {
		const cred = String(args[0] ?? "");
		const id = String(args[1] ?? "");
		if (!id) {
		return errorReturn("messageId is required.", "fields_missing");
		}
		return (await call(cred, "POST", "messages/" + encodeURIComponent(id) + "/trash", {}));
		};
		const untrashMessage = async (args) => {
		const cred = String(args[0] ?? "");
		const id = String(args[1] ?? "");
		if (!id) {
		return errorReturn("messageId is required.", "fields_missing");
		}
		return (await call(cred, "POST", "messages/" + encodeURIComponent(id) + "/untrash", {}));
		};
		const deleteMessage = async (args) => {
		const cred = String(args[0] ?? "");
		const id = String(args[1] ?? "");
		if (!id) {
		return errorReturn("messageId is required.", "fields_missing");
		}
		return (await call(cred, "DELETE", "messages/" + encodeURIComponent(id), null));
		};
		const modifyMessage = async (args) => {
		const cred = String(args[0] ?? "");
		const id = String(args[1] ?? "");
		const opts = args[2] && typeof args[2] === "object" && !Array.isArray(args[2])
		? args[2]
		: {};
		if (!id) {
		return errorReturn("messageId is required.", "fields_missing");
		}
		const add = Array.isArray(opts.addLabelIds)
		? opts.addLabelIds.map((x) => String(x))
		: [];
		const rem = Array.isArray(opts.removeLabelIds)
		? opts.removeLabelIds.map((x) => String(x))
		: [];
		if (add.length === 0 && rem.length === 0) {
		return errorReturn("Provide addLabelIds and/or removeLabelIds.", "fields_missing");
		}
		return (await call(cred, "POST", "messages/" + encodeURIComponent(id) + "/modify", { addLabelIds: add, removeLabelIds: rem }));
		};
		// ── Handlers — Labels ──────────────────────────────────────────────────
		const listLabels = async (args) => {
		const cred = String(args[0] ?? "");
		return (await call(cred, "GET", "labels", null));
		};
		const createLabel = async (args) => {
		const cred = String(args[0] ?? "");
		const fields = args[1] && typeof args[1] === "object" && !Array.isArray(args[1])
		? args[1]
		: {};
		if (!fields.name) {
		return errorReturn("Label `name` is required.", "fields_missing");
		}
		const body = {
		name: String(fields.name),
		labelListVisibility: String(fields.labelListVisibility ?? "labelShow"),
		messageListVisibility: String(fields.messageListVisibility ?? "show"),
		};
		if (fields.color && typeof fields.color === "object") {
		body.color = fields.color;
		}
		return (await call(cred, "POST", "labels", body));
		};
		const deleteLabel = async (args) => {
		const cred = String(args[0] ?? "");
		const labelId = String(args[1] ?? "");
		if (!labelId) {
		return errorReturn("labelId is required.", "fields_missing");
		}
		return (await call(cred, "DELETE", "labels/" + encodeURIComponent(labelId), null));
		};
		// ── Handlers — Threads ─────────────────────────────────────────────────
		const listThreads = async (args) => {
		const cred = String(args[0] ?? "");
		const opts = args[1] && typeof args[1] === "object" && !Array.isArray(args[1])
		? args[1]
		: {};
		const path = "threads" + buildMessagesQuery(opts);
		return (await call(cred, "GET", path, null));
		};
		const getThread = async (args) => {
		const cred = String(args[0] ?? "");
		const id = String(args[1] ?? "");
		const opts = args[2] && typeof args[2] === "object" && !Array.isArray(args[2])
		? args[2]
		: {};
		if (!id) {
		return errorReturn("threadId is required.", "fields_missing");
		}
		const path = "threads/" + encodeURIComponent(id) + buildGetMessageQuery(opts);
		return (await call(cred, "GET", path, null));
		};
		// ── Handlers — Drafts ──────────────────────────────────────────────────
		const listDrafts = async (args) => {
		const cred = String(args[0] ?? "");
		const opts = args[1] && typeof args[1] === "object" && !Array.isArray(args[1])
		? args[1]
		: {};
		const path = "drafts" + buildDraftsQuery(opts);
		return (await call(cred, "GET", path, null));
		};
		const getDraft = async (args) => {
		const cred = String(args[0] ?? "");
		const id = String(args[1] ?? "");
		if (!id) {
		return errorReturn("draftId is required.", "fields_missing");
		}
		return (await call(cred, "GET", "drafts/" + encodeURIComponent(id), null));
		};
		const createDraft = async (args) => {
		const cred = String(args[0] ?? "");
		const fields = args[1] && typeof args[1] === "object" && !Array.isArray(args[1])
		? args[1]
		: {};
		const raw = buildRawMessage(fields);
		if (isErrorReturn(raw))
		return raw;
		const message = { raw: raw.raw };
		if (fields.threadId)
		message.threadId = String(fields.threadId);
		return (await call(cred, "POST", "drafts", { message }));
		};
		const sendDraft = async (args) => {
		const cred = String(args[0] ?? "");
		const id = String(args[1] ?? "");
		if (!id) {
		return errorReturn("draftId is required.", "fields_missing");
		}
		return (await call(cred, "POST", "drafts/send", { id }));
		};
		const deleteDraft = async (args) => {
		const cred = String(args[0] ?? "");
		const id = String(args[1] ?? "");
		if (!id) {
		return errorReturn("draftId is required.", "fields_missing");
		}
		return (await call(cred, "DELETE", "drafts/" + encodeURIComponent(id), null));
		};
		// ── Exports: functions map ─────────────────────────────────────────────
		export const GmailFunctions = {
		// Messages
		listMessages,
		getMessage,
		sendMessage,
		trashMessage,
		untrashMessage,
		deleteMessage,
		modifyMessage,
		// Labels
		listLabels,
		createLabel,
		deleteLabel,
		// Threads
		listThreads,
		getThread,
		// Drafts
		listDrafts,
		getDraft,
		createDraft,
		sendDraft,
		deleteDraft,
		};
		// ── Exports: credential types ──────────────────────────────────────────
		//
		// NOTE: The upstream CredentialFieldType enum in @robinpath/core does not
		// include "select" — the PHP version did. We model `auth_mode` as a plain
		// text field here; hosts that want a dropdown can special-case the slug.
		export const GmailCredentialTypes = [
		{
		slug: CREDENTIAL_TYPE,
		title: "Gmail",
		icon: "mail",
		fields: [
		{
		name: "auth_mode",
		title: "Authentication mode",
		type: "text",
		required: true,
		placeholder: "access_token",
		description: "Choose how this credential authenticates:\n • access_token — Paste an OAuth2 access token obtained externally (easiest for single-user setups).\n • service_account — Google Workspace Domain-Wide Delegation, impersonates a Workspace user.",
		},
		{
		name: "access_token",
		title: "Access token",
		type: "password",
		required: false,
		placeholder: "ya29.a0Af…",
		description: "OAuth2 access token for the target Gmail user. Required when auth_mode = access_token. Tokens expire after ~1 hour — supply refresh_token + client_id + client_secret below for automatic refresh, otherwise you will need to rotate this value manually. Obtain one at https://developers.google.com/oauthplayground (select the Gmail API v1 scopes you need).",
		},
		{
		name: "refresh_token",
		title: "Refresh token",
		type: "password",
		required: false,
		placeholder: "1//0g…",
		description: "Optional. When present with client_id + client_secret, the module will automatically exchange it for a fresh access_token when the current one expires. The refreshed token is cached in-process for ~50 minutes and written back to the credential vault.",
		},
		{
		name: "client_id",
		title: "OAuth client ID",
		type: "text",
		required: false,
		placeholder: "123-abc.apps.googleusercontent.com",
		description: "Optional. The OAuth 2.0 client ID from Google Cloud Console (same one used to generate the refresh_token). Needed for refresh-token flow.",
		},
		{
		name: "client_secret",
		title: "OAuth client secret",
		type: "password",
		required: false,
		placeholder: "GOCSPX-…",
		description: "Optional. The OAuth 2.0 client secret from Google Cloud Console. Needed for refresh-token flow.",
		},
		{
		name: "impersonated_user",
		title: "Impersonated user (service account only)",
		type: "text",
		required: false,
		placeholder: "user@yourcompany.com",
		description: "Required when auth_mode = service_account. The Google Workspace user whose mailbox this credential accesses. The service account must be granted Domain-Wide Delegation for the Gmail scopes in the Workspace admin console.",
		},
		{
		name: "client_email",
		title: "Service account email",
		type: "text",
		required: false,
		placeholder: "name@project-id.iam.gserviceaccount.com",
		description: "Required when auth_mode = service_account. The client_email field from your service-account JSON key.",
		pattern: "@[a-z0-9-]+\\.iam\\.gserviceaccount\\.com$",
		},
		{
		name: "private_key",
		title: "Service account private key (PEM)",
		type: "textarea",
		required: false,
		placeholder: "-----BEGIN PRIVATE KEY-----\n…\n-----END PRIVATE KEY-----\n",
		description: "Required when auth_mode = service_account. The private_key field from your service-account JSON. Paste it as-is, including the BEGIN/END lines.",
		},
		{
		name: "scopes",
		title: "Scopes",
		type: "text",
		required: false,
		placeholder: "https://www.googleapis.com/auth/gmail.modify",
		description: "Space-separated OAuth scopes. Defaults to gmail.modify (read + send + modify, no permanent delete).\n\nCommon alternatives:\n • gmail.readonly — read-only access\n • gmail.send — send-only (compose/send, no read)\n • gmail.compose — compose/send drafts, read drafts\n • gmail.labels — label management only\n • mail.google.com — full access (incl. permanent delete)\n\nSee https://developers.google.com/gmail/api/auth/scopes.",
		},
		],
		},
		];
		// ── Metadata: parameters + errors ──────────────────────────────────────
		const credentialParam = {
		name: "credential",
		title: "Credential",
		description: "Slug of a saved `gmail` credential.",
		dataType: "string",
		formInputType: "resource",
		required: true,
		allowExpression: true,
		placeholder: "my_gmail",
		resource: {
		type: "credential",
		listFn: "credential.list",
		modes: ["list", "expression"],
		searchable: true,
		filter: { type: CREDENTIAL_TYPE },
		},
		};
		const messageIdParam = {
		name: "messageId",
		title: "Message ID",
		description: "Gmail message ID — an opaque lowercase-hex string returned by `listMessages` (e.g. `18c4a5b1e2f00001`). Do not confuse with the RFC 822 `Message-Id` header.",
		dataType: "string",
		formInputType: "text",
		required: true,
		allowExpression: true,
		placeholder: "18c4a5b1e2f00001",
		};
		const threadIdParam = {
		name: "threadId",
		title: "Thread ID",
		description: "Gmail thread (conversation) ID — shares the same format as `messageId`. All messages in a conversation share one `threadId`.",
		dataType: "string",
		formInputType: "text",
		required: true,
		allowExpression: true,
		placeholder: "18c4a5b1e2f00001",
		};
		const draftIdParam = {
		name: "draftId",
		title: "Draft ID",
		description: "Gmail draft ID returned by `createDraft` / `listDrafts` (format `r-1234…`).",
		dataType: "string",
		formInputType: "text",
		required: true,
		allowExpression: true,
		placeholder: "r-1234567890",
		};
		const commonErrors = {
		credential_not_found: "No credential with that slug exists in the vault.",
		token_missing: "Credential has no `access_token` (and no refresh_token for renewal).",
		private_key_missing: "Service-account credential missing `client_email` or `private_key`.",
		jwt_sign_failed: "Could not sign the JWT — `private_key` is malformed (must be PEM).",
		token_exchange_failed: "Google rejected the token exchange — verify the credential values.",
		transport: "Network failure calling Gmail API.",
		gmail_error: "Gmail API returned an error — see `gmail_error.error`.",
		permission_denied: "Access token lacks the required scope, or Domain-Wide Delegation is missing for the service account.",
		rate_limited: "Gmail API rate limit hit — default quota is 250 units/user/second.",
		not_found: "Requested message / thread / draft / label does not exist.",
		quota_exceeded: "Daily Gmail quota exceeded for this account.",
		};
		// ── Function metadata ──────────────────────────────────────────────────
		export const GmailFunctionMetadata = {
		// ── Messages ───────────────────────────────────────────────────────
		listMessages: {
		title: "List / search messages",
		summary: "List or search inbox messages with Gmail search syntax",
		description: "Calls `GET /users/{userId}/messages`. Returns a paginated list of `{id, threadId}` references — call `getMessage` to hydrate each one.\n\nThe Gmail search syntax is identical to the search bar in the Gmail UI:\n • `from:alice@acme.com`\n • `is:unread`\n • `has:attachment label:support older_than:7d`\n • `subject:\"invoice\" -category:promotions`\n\nSee https://support.google.com/mail/answer/7190.",
		group: "messages",
		action: "query",
		icon: "inbox",
		capability: "manage_options",
		sideEffects: ["makes_http_call"],
		idempotent: true,
		since: "1.0.0",
		tags: ["gmail", "inbox", "search", "messages"],
		parameters: [
		credentialParam,
		{
		name: "options",
		title: "Options",
		description: "Recognized keys:\n q : Gmail search query (e.g. 'from:foo@bar is:unread')\n labelIds : array of label IDs to filter (e.g. ['INBOX','UNREAD'])\n maxResults : 1-500 (default 100)\n pageToken : pagination token from a previous response\n includeSpamTrash : bool (default false)",
		dataType: "object",
		formInputType: "json",
		required: false,
		allowExpression: true,
		language: "json",
		rows: 5,
		placeholder: '{\n "q": "is:unread from:support@acme.com",\n "maxResults": 20\n}',
		},
		],
		returnType: "object",
		returnDescription: "{ messages: [{id, threadId}, …], nextPageToken?, resultSizeEstimate }",
		errors: commonErrors,
		examples: [
		{
		title: "Unread mail from support inbox",
		code: 'gmail.listMessages "my_gmail" {q: "from:support@acme.com is:unread", maxResults: 20}',
		},
		{
		title: "All attachments received this week",
		code: 'gmail.listMessages "my_gmail" {q: "has:attachment newer_than:7d"}',
		},
		],
		example: 'gmail.listMessages "my_gmail" {q:"is:unread", maxResults:10}',
		},
		getMessage: {
		title: "Get message",
		summary: "Fetch a single message by ID",
		description: "Calls `GET /users/{userId}/messages/{id}`. Response shape depends on `format`:\n • full (default): `{id, threadId, labelIds, snippet, payload: {headers, parts, body}, sizeEstimate}`\n • metadata: only headers (useful for inspecting subject/from/to without fetching body bytes)\n • raw: full RFC 2822 source as base64url string in `raw`",
		group: "messages",
		action: "read",
		icon: "mail",
		capability: "manage_options",
		sideEffects: ["makes_http_call"],
		idempotent: true,
		since: "1.0.0",
		tags: ["gmail", "message", "read"],
		parameters: [
		credentialParam,
		messageIdParam,
		{
		name: "options",
		title: "Options",
		description: "Recognized keys:\n format : 'minimal' \| 'metadata' \| 'full' (default) \| 'raw'\n metadataHeaders: when format=metadata, array of header names to return (e.g. ['From','Subject'])",
		dataType: "object",
		formInputType: "json",
		required: false,
		allowExpression: true,
		language: "json",
		rows: 4,
		advanced: true,
		},
		],
		returnType: "object",
		returnDescription: "Message resource — shape varies by format.",
		errors: commonErrors,
		example: 'gmail.getMessage "my_gmail" "18c4a5b1e2f00001"',
		},
		sendMessage: {
		title: "Send email",
		summary: "Compose and send an email",
		description: "Builds an RFC 2822 MIME message from the supplied fields, base64url-encodes it, and POSTs to `/messages/send`.\n\nSupports plain text, HTML, or both (multipart/alternative — most clients will render the HTML, fall back to text). The `from` field is optional — Gmail will use the authenticated user's address if omitted. CC/BCC lists may be strings ('a@b, c@d') or arrays.\n\nAttachments are not yet supported in this first pass — use the raw API via `http.post` if you need them.",
		group: "messages",
		action: "write",
		icon: "send",
		capability: "manage_options",
		sideEffects: ["makes_http_call", "sends_email"],
		idempotent: false,
		since: "1.0.0",
		tags: ["gmail", "send", "email", "compose"],
		parameters: [
		credentialParam,
		{
		name: "fields",
		title: "Fields",
		description: "Email fields:\n to : 'a@b.com' OR ['a@b.com','c@d.com'] OR 'Alice <a@b.com>' (required)\n subject : string (required)\n text : plain-text body\n html : HTML body (at least one of text/html is required)\n from : override sender ('Me <me@gmail.com>'); defaults to authenticated user\n cc, bcc : same shapes as `to`\n replyTo : Reply-To header value\n threadId : append to an existing thread (reply)\n inReplyTo : RFC Message-Id of the message being replied to (sets References + In-Reply-To)\n headers : {header-name: value} extra custom headers",
		dataType: "object",
		formInputType: "json",
		required: true,
		allowExpression: true,
		language: "json",
		rows: 8,
		placeholder: '{\n "to": "customer@example.com",\n "subject": "Welcome",\n "html": "<p>Thanks for signing up!</p>",\n "text": "Thanks for signing up!"\n}',
		},
		],
		returnType: "object",
		returnDescription: "{ id, threadId, labelIds } — the created message resource.",
		errors: commonErrors,
		examples: [
		{
		title: "Welcome email",
		code: 'gmail.sendMessage "my_gmail" {\n to: {{ user.email }},\n subject: "Welcome to Brand",\n html: "<h1>Hi {{ user.name }}</h1><p>Glad you\'re here.</p>"\n}',
		},
		{
		title: "Reply in thread",
		code: 'gmail.sendMessage "my_gmail" {\n to: "customer@example.com",\n subject: "Re: Invoice #1234",\n text: "Thanks, processed!",\n threadId: {{ message.threadId }}\n}',
		},
		],
		example: 'gmail.sendMessage "my_gmail" {to:"a@b.com", subject:"hi", text:"hello"}',
		},
		trashMessage: {
		title: "Move message to trash",
		summary: "Move a message to the Trash label",
		description: "Calls `POST /messages/{id}/trash`. Reversible via `untrashMessage`. Trashed messages are auto-deleted after 30 days by Gmail.",
		group: "messages",
		action: "write",
		icon: "trash",
		capability: "manage_options",
		sideEffects: ["makes_http_call"],
		idempotent: true,
		since: "1.0.0",
		tags: ["gmail", "trash", "message"],
		parameters: [credentialParam, messageIdParam],
		returnType: "object",
		errors: commonErrors,
		example: 'gmail.trashMessage "my_gmail" "18c4a5b1e2f00001"',
		},
		untrashMessage: {
		title: "Restore message from trash",
		summary: "Remove the TRASH label",
		description: "Calls `POST /messages/{id}/untrash`. Restores a message that was trashed (works until Gmail auto-purges after 30 days).",
		group: "messages",
		action: "write",
		icon: "rotate-ccw",
		capability: "manage_options",
		sideEffects: ["makes_http_call"],
		idempotent: true,
		since: "1.0.0",
		tags: ["gmail", "trash", "restore"],
		parameters: [credentialParam, messageIdParam],
		returnType: "object",
		errors: commonErrors,
		example: 'gmail.untrashMessage "my_gmail" "18c4a5b1e2f00001"',
		},
		deleteMessage: {
		title: "Permanently delete message",
		summary: "Delete a message forever (bypasses trash)",
		description: "Calls `DELETE /messages/{id}`. Permanent — cannot be undone. Requires the full `mail.google.com` scope (the default `gmail.modify` scope cannot permanently delete). Prefer `trashMessage` unless you have a specific retention requirement.",
		group: "messages",
		action: "delete",
		icon: "trash-2",
		capability: "manage_options",
		sideEffects: ["makes_http_call"],
		idempotent: true,
		since: "1.0.0",
		tags: ["gmail", "delete", "permanent"],
		parameters: [credentialParam, messageIdParam],
		returnType: "object",
		errors: commonErrors,
		example: 'gmail.deleteMessage "my_gmail" "18c4a5b1e2f00001"',
		},
		modifyMessage: {
		title: "Add or remove labels",
		summary: "Apply/remove labels (read, star, archive, custom labels)",
		description: "Calls `POST /messages/{id}/modify`. Used for mark-as-read/unread, star/unstar, archive, and any custom label.\n\nCommon system labels:\n • UNREAD — remove to mark as read\n • STARRED — add/remove star\n • IMPORTANT — remove to un-flag\n • INBOX — remove to archive\n • SPAM / TRASH — moderation labels",
		group: "messages",
		action: "write",
		icon: "tag",
		capability: "manage_options",
		sideEffects: ["makes_http_call"],
		idempotent: true,
		since: "1.0.0",
		tags: ["gmail", "label", "modify", "archive", "read"],
		parameters: [
		credentialParam,
		messageIdParam,
		{
		name: "options",
		title: "Label changes",
		description: "Recognized keys:\n addLabelIds : array of label IDs to add\n removeLabelIds : array of label IDs to remove\n\nAt least one of the two must be non-empty.",
		dataType: "object",
		formInputType: "json",
		required: true,
		allowExpression: true,
		language: "json",
		rows: 4,
		placeholder: '{\n "removeLabelIds": ["UNREAD"],\n "addLabelIds": ["Label_123"]\n}',
		},
		],
		returnType: "object",
		errors: commonErrors,
		examples: [
		{
		title: "Mark as read",
		code: 'gmail.modifyMessage "my_gmail" "{{ message.id }}" {removeLabelIds: ["UNREAD"]}',
		},
		{
		title: "Archive (remove INBOX label)",
		code: 'gmail.modifyMessage "my_gmail" "{{ message.id }}" {removeLabelIds: ["INBOX"]}',
		},
		],
		example: 'gmail.modifyMessage "my_gmail" "18c4…" {removeLabelIds:["UNREAD"]}',
		},
		// ── Labels ─────────────────────────────────────────────────────────
		listLabels: {
		title: "List labels",
		summary: "Fetch all labels in the mailbox (system + user)",
		description: "Calls `GET /users/{userId}/labels`. Returns all system labels (INBOX, UNREAD, STARRED, IMPORTANT, SPAM, TRASH, SENT, DRAFT, CATEGORY_*) plus user-created labels.",
		group: "labels",
		action: "query",
		icon: "tags",
		capability: "manage_options",
		sideEffects: ["makes_http_call"],
		idempotent: true,
		since: "1.0.0",
		tags: ["gmail", "labels", "list"],
		parameters: [credentialParam],
		returnType: "object",
		returnDescription: '{ labels: [{id, name, type: "system"\|"user", messageListVisibility?, labelListVisibility?}, …] }',
		errors: commonErrors,
		example: 'gmail.listLabels "my_gmail"',
		},
		createLabel: {
		title: "Create label",
		summary: "Create a user label",
		description: 'Calls `POST /users/{userId}/labels`. Label names support nesting via `/` (e.g. `"Clients/Acme"`). Returns the created label with its assigned ID (typically `Label_N`).',
		group: "labels",
		action: "write",
		icon: "tag",
		capability: "manage_options",
		sideEffects: ["makes_http_call"],
		idempotent: false,
		since: "1.0.0",
		tags: ["gmail", "label", "create"],
		parameters: [
		credentialParam,
		{
		name: "fields",
		title: "Label fields",
		description: "Recognized keys:\n name : string (required) — e.g. 'Customers/VIP'\n labelListVisibility : 'labelShow' (default) \| 'labelShowIfUnread' \| 'labelHide'\n messageListVisibility : 'show' (default) \| 'hide'\n color : {textColor, backgroundColor} — hex, only preset values accepted",
		dataType: "object",
		formInputType: "json",
		required: true,
		allowExpression: true,
		language: "json",
		rows: 5,
		placeholder: '{\n "name": "Customers/VIP"\n}',
		},
		],
		returnType: "object",
		errors: commonErrors,
		example: 'gmail.createLabel "my_gmail" {name:"Customers/VIP"}',
		},
		deleteLabel: {
		title: "Delete label",
		summary: "Delete a user label",
		description: "Calls `DELETE /users/{userId}/labels/{id}`. Permanent. Messages that had this label remain, but lose the label. Cannot delete system labels.",
		group: "labels",
		action: "delete",
		icon: "tag-off",
		capability: "manage_options",
		sideEffects: ["makes_http_call"],
		idempotent: true,
		since: "1.0.0",
		tags: ["gmail", "label", "delete"],
		parameters: [
		credentialParam,
		{
		name: "labelId",
		title: "Label ID",
		description: "User label ID (typically `Label_N`). Use `listLabels` to look up IDs by name.",
		dataType: "string",
		formInputType: "text",
		required: true,
		allowExpression: true,
		placeholder: "Label_123",
		},
		],
		returnType: "object",
		errors: commonErrors,
		example: 'gmail.deleteLabel "my_gmail" "Label_123"',
		},
		// ── Threads ────────────────────────────────────────────────────────
		listThreads: {
		title: "List / search threads",
		summary: "List conversation threads (same query syntax as messages)",
		description: "Calls `GET /users/{userId}/threads`. Returns a paginated list of thread references. Threads are conversations — all messages that share a subject and participant set.",
		group: "threads",
		action: "query",
		icon: "messages-square",
		capability: "manage_options",
		sideEffects: ["makes_http_call"],
		idempotent: true,
		since: "1.0.0",
		tags: ["gmail", "thread", "conversation"],
		parameters: [
		credentialParam,
		{
		name: "options",
		title: "Options",
		description: "Recognized keys (identical to listMessages):\n q, labelIds, maxResults, pageToken, includeSpamTrash",
		dataType: "object",
		formInputType: "json",
		required: false,
		allowExpression: true,
		language: "json",
		rows: 5,
		advanced: true,
		},
		],
		returnType: "object",
		returnDescription: "{ threads: [{id, snippet, historyId}, …], nextPageToken?, resultSizeEstimate }",
		errors: commonErrors,
		example: 'gmail.listThreads "my_gmail" {q:"label:support is:unread"}',
		},
		getThread: {
		title: "Get thread",
		summary: "Fetch a full conversation including all messages",
		description: "Calls `GET /users/{userId}/threads/{id}`. Returns the thread metadata plus an expanded `messages` array (same shape as `getMessage`, format=full).",
		group: "threads",
		action: "read",
		icon: "messages-square",
		capability: "manage_options",
		sideEffects: ["makes_http_call"],
		idempotent: true,
		since: "1.0.0",
		tags: ["gmail", "thread", "read"],
		parameters: [
		credentialParam,
		threadIdParam,
		{
		name: "options",
		title: "Options",
		description: "Recognized keys:\n format : 'minimal' \| 'metadata' \| 'full' (default)\n metadataHeaders : array of header names (when format=metadata)",
		dataType: "object",
		formInputType: "json",
		required: false,
		allowExpression: true,
		language: "json",
		rows: 3,
		advanced: true,
		},
		],
		returnType: "object",
		errors: commonErrors,
		example: 'gmail.getThread "my_gmail" "18c4a5b1e2f00001"',
		},
		// ── Drafts ─────────────────────────────────────────────────────────
		listDrafts: {
		title: "List drafts",
		summary: "List unsent drafts",
		description: "Calls `GET /users/{userId}/drafts`. Returns `{drafts: [{id, message:{id, threadId}}, …]}` — use `getDraft` to fetch each draft's contents.",
		group: "drafts",
		action: "query",
		icon: "file-text",
		capability: "manage_options",
		sideEffects: ["makes_http_call"],
		idempotent: true,
		since: "1.0.0",
		tags: ["gmail", "draft", "list"],
		parameters: [
		credentialParam,
		{
		name: "options",
		title: "Options",
		description: "Recognized keys:\n maxResults : 1-500 (default 100)\n pageToken : pagination token\n q : Gmail search query",
		dataType: "object",
		formInputType: "json",
		required: false,
		allowExpression: true,
		language: "json",
		rows: 3,
		advanced: true,
		},
		],
		returnType: "object",
		errors: commonErrors,
		example: 'gmail.listDrafts "my_gmail" {maxResults:50}',
		},
		getDraft: {
		title: "Get draft",
		summary: "Fetch a draft by ID",
		description: "Calls `GET /users/{userId}/drafts/{id}`. Returns `{id, message: {…}}` with the draft's full message payload.",
		group: "drafts",
		action: "read",
		icon: "file-text",
		capability: "manage_options",
		sideEffects: ["makes_http_call"],
		idempotent: true,
		since: "1.0.0",
		tags: ["gmail", "draft", "read"],
		parameters: [credentialParam, draftIdParam],
		returnType: "object",
		errors: commonErrors,
		example: 'gmail.getDraft "my_gmail" "r-1234567890"',
		},
		createDraft: {
		title: "Create draft",
		summary: "Save a new draft email",
		description: "Calls `POST /users/{userId}/drafts`. Accepts the same `fields` object as `sendMessage`, but saves it as a draft instead of sending. Useful for AI-assisted reply workflows where a human approves before sending.",
		group: "drafts",
		action: "write",
		icon: "file-plus",
		capability: "manage_options",
		sideEffects: ["makes_http_call"],
		idempotent: false,
		since: "1.0.0",
		tags: ["gmail", "draft", "create"],
		parameters: [
		credentialParam,
		{
		name: "fields",
		title: "Fields",
		description: "Same shape as `sendMessage.fields` — to/subject/text/html/cc/bcc/from/replyTo/threadId/inReplyTo/headers.",
		dataType: "object",
		formInputType: "json",
		required: true,
		allowExpression: true,
		language: "json",
		rows: 8,
		},
		],
		returnType: "object",
		returnDescription: "{ id, message: {id, threadId, labelIds} }",
		errors: commonErrors,
		example: 'gmail.createDraft "my_gmail" {to:"a@b.com", subject:"hi", text:"hello"}',
		},
		sendDraft: {
		title: "Send draft",
		summary: "Send a previously-created draft",
		description: "Calls `POST /users/{userId}/drafts/send`. Promotes the draft to a sent message. The draft is deleted as a side effect — the returned message has a new `id`.",
		group: "drafts",
		action: "write",
		icon: "send",
		capability: "manage_options",
		sideEffects: ["makes_http_call", "sends_email"],
		idempotent: false,
		since: "1.0.0",
		tags: ["gmail", "draft", "send"],
		parameters: [credentialParam, draftIdParam],
		returnType: "object",
		returnDescription: "{ id, threadId, labelIds } — the now-sent message.",
		errors: commonErrors,
		example: 'gmail.sendDraft "my_gmail" "r-1234567890"',
		},
		deleteDraft: {
		title: "Delete draft",
		summary: "Permanently discard a draft",
		description: "Calls `DELETE /users/{userId}/drafts/{id}`. Permanent — the underlying message is also removed.",
		group: "drafts",
		action: "delete",
		icon: "trash",
		capability: "manage_options",
		sideEffects: ["makes_http_call"],
		idempotent: true,
		since: "1.0.0",
		tags: ["gmail", "draft", "delete"],
		parameters: [credentialParam, draftIdParam],
		returnType: "object",
		errors: commonErrors,
		example: 'gmail.deleteDraft "my_gmail" "r-1234567890"',
		},
		};
		// ── Module metadata ────────────────────────────────────────────────────
		export const GmailModuleMetadata = {
		slug: "gmail",
		title: "Gmail",
		summary: "List, search, send, label, and draft emails via the Gmail REST API",
		description: 'Use Gmail as a first-class automation surface — trigger on unread mail, auto-label customer support inbound, draft AI-generated replies, send personalized outreach, archive processed messages.\n\nAuthentication — two modes, same credential type:\n\n 1. `access_token` (recommended for single-user setups) — Generate an OAuth2 token at https://developers.google.com/oauthplayground with the `https://www.googleapis.com/auth/gmail.modify` scope (or tighter) and paste it in. Tokens expire in ~1h; supply a `refresh_token` + client ID/secret for automatic renewal.\n\n 2. `service_account` (Google Workspace admins) — Create a service account, grant it Domain-Wide Delegation in the Workspace admin console for the Gmail scopes, and specify the `impersonated_user` whose mailbox to access.\n\nAll operations run against `users/{impersonated_user or "me"}` — `me` resolves to the account that minted the access token.\n\nDocs: https://developers.google.com/gmail/api/reference/rest',
		category: "communication",
		icon: "icon.svg",
		color: "#EA4335",
		version: "0.2.0",
		docsUrl: "https://docs.robinpath.com/modules/gmail",
		status: "stable",
		requires: [],
		minNodeVersion: "18.0.0",
		credentialsType: CREDENTIAL_TYPE,
		operationGroups: {
		messages: {
		title: "Messages",
		description: "List, read, send, trash, delete, modify labels.",
		order: 1,
		},
		labels: {
		title: "Labels",
		description: "Manage inbox labels (system + user-defined).",
		order: 2,
		},
		threads: {
		title: "Threads",
		description: "Conversation-level operations.",
		order: 3,
		},
		drafts: {
		title: "Drafts",
		description: "Compose, update, send, and delete drafts.",
		order: 4,
		},
		},
		methods: Object.keys(GmailFunctions),
		};
		//# sourceMappingURL=gmail.js.map

+1

dist/gmail.js.map

+6

dist/index.d.ts

		import type { ModuleAdapter } from "@robinpath/core";
		declare const GmailModule: ModuleAdapter;
		export default GmailModule;
		export { GmailModule };
		export { GmailFunctions, GmailFunctionMetadata, GmailModuleMetadata, GmailCredentialTypes, configureGmail, } from "./gmail.js";
		//# sourceMappingURL=index.d.ts.map

+1

dist/index.d.ts.map

{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AASrD,QAAA,MAAM,WAAW,EAAE,aAQlB,CAAC;AAEF,eAAe,WAAW,CAAC;AAC3B,OAAO,EAAE,WAAW,EAAE,CAAC;AACvB,OAAO,EACL,cAAc,EACd,qBAAqB,EACrB,mBAAmB,EACnB,oBAAoB,EACpB,cAAc,GACf,MAAM,YAAY,CAAC"}

+14

dist/index.js

		import { GmailFunctions, GmailFunctionMetadata, GmailModuleMetadata, GmailCredentialTypes, configureGmail, } from "./gmail.js";
		const GmailModule = {
		name: "gmail",
		functions: GmailFunctions,
		functionMetadata: GmailFunctionMetadata,
		moduleMetadata: GmailModuleMetadata,
		credentialTypes: GmailCredentialTypes,
		configure: configureGmail,
		global: false,
		};
		export default GmailModule;
		export { GmailModule };
		export { GmailFunctions, GmailFunctionMetadata, GmailModuleMetadata, GmailCredentialTypes, configureGmail, } from "./gmail.js";
		//# sourceMappingURL=index.js.map

+1

dist/index.js.map

{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,OAAO,EACL,cAAc,EACd,qBAAqB,EACrB,mBAAmB,EACnB,oBAAoB,EACpB,cAAc,GACf,MAAM,YAAY,CAAC;AAEpB,MAAM,WAAW,GAAkB;IACjC,IAAI,EAAE,OAAO;IACb,SAAS,EAAE,cAAc;IACzB,gBAAgB,EAAE,qBAAqB;IACvC,cAAc,EAAE,mBAAmB;IACnC,eAAe,EAAE,oBAAoB;IACrC,SAAS,EAAE,cAAc;IACzB,MAAM,EAAE,KAAK;CACd,CAAC;AAEF,eAAe,WAAW,CAAC;AAC3B,OAAO,EAAE,WAAW,EAAE,CAAC;AACvB,OAAO,EACL,cAAc,EACd,qBAAqB,EACrB,mBAAmB,EACnB,oBAAoB,EACpB,cAAc,GACf,MAAM,YAAY,CAAC"}

+22

-8

package.json

		{
		"name": "@robinpath/gmail",
		"version": "0.1.1",
		"version": "0.3.0",
		"publishConfig": {
		@@ -23,12 +23,20 @@ "access": "public"
		"peerDependencies": {
		"@robinpath/core": ">=0.20.0"
		"@robinpath/core": ">=0.40.0"
		},
		"devDependencies": {
		"@robinpath/core": "^0.30.1",
		"@robinpath/core": "^0.40.0",
		"typescript": "^5.6.0"
		},
		"description": "Gmail module for RobinPath.",
		"description": "Gmail integration — list/search messages, send email, manage labels, threads, and drafts via the Gmail REST API. Supports OAuth2 access tokens (easiest) or service-account with Domain-Wide Delegation.",
		"keywords": [
		"gmail",
		"productivity"
		"productivity",
		"google",
		"email",
		"mail",
		"oauth2",
		"service-account",
		"inbox",
		"drafts",
		"labels"
		],
		@@ -38,7 +46,13 @@ "license": "MIT",
		"category": "productivity",
		"type": "integration",
		"auth": "api-key",
		"type": "module",
		"auth": "credential-vault",
		"functionCount": 17,
		"baseUrl": "https://gmail.googleapis.com"
		"baseUrl": "https://gmail.googleapis.com",
		"language": "nodejs",
		"platforms": [
		"cloud",
		"cli",
		"desktop"
		]
		}
		}

+1

-1

README.md

		@@ -22,3 +22,3 @@ # @robinpath/gmail
		```bash
		npm install @robinpath/gmail
		robinpath add @robinpath/gmail
		```
		@@ -25,0 +25,0 @@

@robinpath/gmail - npm Package Compare versions

New alerts

Fixed alerts

Improved metrics

Worsened metrics