@mcp-z/mcp-gmail 1.0.0

package/dist/esm/email/messages/messages.js

@@ -0,0 +1,91 @@
+import { buildContentForItems } from '@mcp-z/email';
+import { safeBase64Decode } from '../../lib/base64-encoding.js';
+import { toIsoUtc } from '../../lib/date-conversion.js';
+import { extractEmails, extractFrom } from '../parsing/headers-utils.js';
+export { buildContentForItems };
+// Convert a Gmail messages.get() response into canonical row shape used by sheets writer
+// [id, provider, threadId, to, from, cc, bcc, date, subject, labels, snippet, body]
+export function toRowFromGmail(msg = {}, opts = {
+    body: false,
+    addressFormat: 'email'
+}) {
+    var _ref, _ref1, _headerObj_To, _headerObj_From, _ref2, _headerObj_Cc, _headerObj_Bcc, _ref3, _headerObj_Subject, _ref4;
+    var _msg_payload;
+    const headers = (msg === null || msg === void 0 ? void 0 : (_msg_payload = msg.payload) === null || _msg_payload === void 0 ? void 0 : _msg_payload.headers) || [];
+    const headerObj = Object.fromEntries((headers || []).map((h)=>{
+        var _ref, _ref1;
+        return [
+            String((_ref = h === null || h === void 0 ? void 0 : h.name) !== null && _ref !== void 0 ? _ref : ''),
+            String((_ref1 = h === null || h === void 0 ? void 0 : h.value) !== null && _ref1 !== void 0 ? _ref1 : '')
+        ];
+    }));
+    const id = (_ref = msg === null || msg === void 0 ? void 0 : msg.id) !== null && _ref !== void 0 ? _ref : '';
+    const provider = 'gmail';
+    const threadId = (_ref1 = msg === null || msg === void 0 ? void 0 : msg.threadId) !== null && _ref1 !== void 0 ? _ref1 : '';
+    const to = extractEmails((_headerObj_To = headerObj.To) !== null && _headerObj_To !== void 0 ? _headerObj_To : '').join(', ');
+    const fromInfo = extractFrom((_headerObj_From = headerObj.From) !== null && _headerObj_From !== void 0 ? _headerObj_From : '');
+    const from = (_ref2 = fromInfo && fromInfo.address || headerObj.From) !== null && _ref2 !== void 0 ? _ref2 : '';
+    const cc = extractEmails((_headerObj_Cc = headerObj.Cc) !== null && _headerObj_Cc !== void 0 ? _headerObj_Cc : '').join(', ');
+    const bcc = extractEmails((_headerObj_Bcc = headerObj.Bcc) !== null && _headerObj_Bcc !== void 0 ? _headerObj_Bcc : '').join(', ');
+    const date = (_ref3 = toIsoUtc(headerObj.Date) || headerObj.Date) !== null && _ref3 !== void 0 ? _ref3 : '';
+    const subject = (_headerObj_Subject = headerObj.Subject) !== null && _headerObj_Subject !== void 0 ? _headerObj_Subject : '';
+    const labelIds = Array.isArray(msg === null || msg === void 0 ? void 0 : msg.labelIds) ? msg.labelIds : [];
+    const labels = labelIds.join(';');
+    const snippet = (_ref4 = msg === null || msg === void 0 ? void 0 : msg.snippet) !== null && _ref4 !== void 0 ? _ref4 : '';
+    let bodyFull = '';
+    if (opts === null || opts === void 0 ? void 0 : opts.body) {
+        var _msg_payload1, _msg_payload2;
+        const parts = (msg === null || msg === void 0 ? void 0 : (_msg_payload1 = msg.payload) === null || _msg_payload1 === void 0 ? void 0 : _msg_payload1.parts) || [];
+        const findText = (partsArr)=>{
+            for (const p of partsArr || []){
+                if (p && typeof p === 'object' && 'mimeType' in p && 'body' in p) {
+                    if (p.mimeType === 'text/plain' && p.body && typeof p.body === 'object' && 'data' in p.body) {
+                        return p.body.data;
+                    }
+                }
+                if (p && typeof p === 'object' && 'parts' in p) {
+                    const nested = findText(p.parts);
+                    if (nested) return nested;
+                }
+            }
+            return null;
+        };
+        const raw = findText(parts) || ((msg === null || msg === void 0 ? void 0 : (_msg_payload2 = msg.payload) === null || _msg_payload2 === void 0 ? void 0 : _msg_payload2.body) && typeof msg.payload.body === 'object' && 'data' in msg.payload.body ? msg.payload.body.data : null) || null;
+        if (raw) {
+            bodyFull = safeBase64Decode(raw);
+        } else {
+            const findHtml = (partsArr)=>{
+                for (const p of partsArr || []){
+                    if (p && typeof p === 'object' && 'mimeType' in p && 'body' in p) {
+                        if (p.mimeType === 'text/html' && p.body && typeof p.body === 'object' && 'data' in p.body) {
+                            return p.body.data;
+                        }
+                    }
+                    if (p && typeof p === 'object' && 'parts' in p) {
+                        const nested = findHtml(p.parts);
+                        if (nested) return nested;
+                    }
+                }
+                return null;
+            };
+            const htmlPart = findHtml(parts);
+            if (htmlPart) {
+                bodyFull = safeBase64Decode(htmlPart).replace(/\r\n?/g, '\n');
+            }
+        }
+    }
+    return [
+        id,
+        provider,
+        threadId,
+        to,
+        from,
+        cc,
+        bcc,
+        date,
+        subject,
+        labels,
+        snippet,
+        bodyFull
+    ];
+}

package/dist/esm/email/messages/messages.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["/Users/kevin/Dev/Projects/ai/mcp-z/servers/mcp-gmail/src/email/messages/messages.ts"],"sourcesContent":["import { buildContentForItems } from '@mcp-z/email';\nimport type { gmail_v1 } from 'googleapis';\nimport { safeBase64Decode } from '../../lib/base64-encoding.js';\nimport { toIsoUtc } from '../../lib/date-conversion.js';\nimport { extractEmails, extractFrom } from '../parsing/headers-utils.js';\n\nexport { buildContentForItems };\n\n// Convert a Gmail messages.get() response into canonical row shape used by sheets writer\n// [id, provider, threadId, to, from, cc, bcc, date, subject, labels, snippet, body]\nexport function toRowFromGmail(msg: gmail_v1.Schema$Message = {}, opts: { body?: boolean; addressFormat?: 'email' | string } = { body: false, addressFormat: 'email' }) {\n  const headers = msg?.payload?.headers || [];\n  const headerObj: Record<string, string> = Object.fromEntries((headers || []).map((h) => [String(h?.name ?? ''), String(h?.value ?? '')]));\n  const id = msg?.id ?? '';\n  const provider = 'gmail';\n  const threadId = msg?.threadId ?? '';\n  const to = extractEmails(headerObj.To ?? '').join(', ');\n  const fromInfo = extractFrom(headerObj.From ?? '');\n  const from = ((fromInfo && fromInfo.address) || headerObj.From) ?? '';\n  const cc = extractEmails(headerObj.Cc ?? '').join(', ');\n  const bcc = extractEmails(headerObj.Bcc ?? '').join(', ');\n  const date = (toIsoUtc(headerObj.Date) || headerObj.Date) ?? '';\n  const subject = headerObj.Subject ?? '';\n  const labelIds = Array.isArray(msg?.labelIds) ? (msg.labelIds as string[]) : [];\n  const labels = labelIds.join(';');\n  const snippet = msg?.snippet ?? '';\n\n  let bodyFull = '';\n  if (opts?.body) {\n    const parts = msg?.payload?.parts || [];\n    const findText = (partsArr: unknown[]): string | null => {\n      for (const p of partsArr || []) {\n        if (p && typeof p === 'object' && 'mimeType' in p && 'body' in p) {\n          if (p.mimeType === 'text/plain' && p.body && typeof p.body === 'object' && 'data' in p.body) {\n            return p.body.data as string;\n          }\n        }\n        if (p && typeof p === 'object' && 'parts' in p) {\n          const nested = findText(p.parts as unknown[]);\n          if (nested) return nested;\n        }\n      }\n      return null;\n    };\n    const raw = findText(parts as unknown[]) || (msg?.payload?.body && typeof msg.payload.body === 'object' && 'data' in msg.payload.body ? msg.payload.body.data : null) || null;\n    if (raw) {\n      bodyFull = safeBase64Decode(raw as string);\n    } else {\n      const findHtml = (partsArr: unknown[]): string | null => {\n        for (const p of partsArr || []) {\n          if (p && typeof p === 'object' && 'mimeType' in p && 'body' in p) {\n            if (p.mimeType === 'text/html' && p.body && typeof p.body === 'object' && 'data' in p.body) {\n              return p.body.data as string;\n            }\n          }\n          if (p && typeof p === 'object' && 'parts' in p) {\n            const nested = findHtml(p.parts as unknown[]);\n            if (nested) return nested;\n          }\n        }\n        return null;\n      };\n      const htmlPart = findHtml(parts as unknown[]);\n      if (htmlPart) {\n        bodyFull = safeBase64Decode(htmlPart).replace(/\\r\\n?/g, '\\n');\n      }\n    }\n  }\n  return [id, provider, threadId, to, from, cc, bcc, date, subject, labels, snippet, bodyFull];\n}\n"],"names":["buildContentForItems","safeBase64Decode","toIsoUtc","extractEmails","extractFrom","toRowFromGmail","msg","opts","body","addressFormat","headerObj","headers","payload","Object","fromEntries","map","h","String","name","value","id","provider","threadId","to","To","join","fromInfo","From","from","address","cc","Cc","bcc","Bcc","date","Date","subject","Subject","labelIds","Array","isArray","labels","snippet","bodyFull","parts","findText","partsArr","p","mimeType","data","nested","raw","findHtml","htmlPart","replace"],"mappings":"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"}

package/dist/esm/email/parsing/header-parsing.d.ts

@@ -0,0 +1 @@
+export { extractEmails, extractFrom } from './headers-utils.js';

package/dist/esm/email/parsing/header-parsing.js

@@ -0,0 +1 @@
+export { extractEmails, extractFrom } from './headers-utils.js';

package/dist/esm/email/parsing/header-parsing.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["/Users/kevin/Dev/Projects/ai/mcp-z/servers/mcp-gmail/src/email/parsing/header-parsing.ts"],"sourcesContent":["export { extractEmails, extractFrom } from './headers-utils.js';\n"],"names":["extractEmails","extractFrom"],"mappings":"AAAA,SAASA,aAAa,EAAEC,WAAW,QAAQ,qBAAqB"}

package/dist/esm/email/parsing/headers-utils.d.ts

@@ -0,0 +1,5 @@
+export declare function extractEmails(header?: string): string[];
+export declare function extractFrom(header?: string): {
+    address?: string;
+    name?: string;
+} | undefined;

package/dist/esm/email/parsing/headers-utils.js

@@ -0,0 +1,25 @@
+export function extractEmails(header) {
+    if (!header) return [];
+    const matches = header.match(/[A-Z0-9._%+-]+@[A-Z0-9.-]+\.[A-Z]{2,}/gi) || [];
+    return matches.map((s)=>s.trim());
+}
+export function extractFrom(header) {
+    if (!header) return undefined;
+    const m = header.match(/^(.*)<([^>]+)>/);
+    if (m) {
+        const rawName = m[1];
+        const name = rawName ? rawName.replace(/"/g, '').trim() : undefined;
+        const addr = m[2] ? m[2].trim() : undefined;
+        const result = {};
+        if (addr) result.address = addr;
+        if (name) result.name = name;
+        return result;
+    }
+    const emails = extractEmails(header);
+    if (emails[0]) return {
+        address: emails[0]
+    };
+    return {
+        address: header.trim()
+    };
+}

package/dist/esm/email/parsing/headers-utils.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["/Users/kevin/Dev/Projects/ai/mcp-z/servers/mcp-gmail/src/email/parsing/headers-utils.ts"],"sourcesContent":["export function extractEmails(header?: string): string[] {\n  if (!header) return [];\n  const matches = header.match(/[A-Z0-9._%+-]+@[A-Z0-9.-]+\\.[A-Z]{2,}/gi) || [];\n  return matches.map((s: string) => s.trim());\n}\n\nexport function extractFrom(header?: string): { address?: string; name?: string } | undefined {\n  if (!header) return undefined;\n  const m = header.match(/^(.*)<([^>]+)>/);\n  if (m) {\n    const rawName = m[1];\n    const name = rawName ? rawName.replace(/\"/g, '').trim() : undefined;\n    const addr = m[2] ? m[2].trim() : undefined;\n    const result: { address?: string; name?: string } = {};\n    if (addr) result.address = addr;\n    if (name) result.name = name;\n    return result;\n  }\n  const emails = extractEmails(header);\n  if (emails[0]) return { address: emails[0] };\n  return { address: header.trim() };\n}\n"],"names":["extractEmails","header","matches","match","map","s","trim","extractFrom","undefined","m","rawName","name","replace","addr","result","address","emails"],"mappings":"AAAA,OAAO,SAASA,cAAcC,MAAe;IAC3C,IAAI,CAACA,QAAQ,OAAO,EAAE;IACtB,MAAMC,UAAUD,OAAOE,KAAK,CAAC,8CAA8C,EAAE;IAC7E,OAAOD,QAAQE,GAAG,CAAC,CAACC,IAAcA,EAAEC,IAAI;AAC1C;AAEA,OAAO,SAASC,YAAYN,MAAe;IACzC,IAAI,CAACA,QAAQ,OAAOO;IACpB,MAAMC,IAAIR,OAAOE,KAAK,CAAC;IACvB,IAAIM,GAAG;QACL,MAAMC,UAAUD,CAAC,CAAC,EAAE;QACpB,MAAME,OAAOD,UAAUA,QAAQE,OAAO,CAAC,MAAM,IAAIN,IAAI,KAAKE;QAC1D,MAAMK,OAAOJ,CAAC,CAAC,EAAE,GAAGA,CAAC,CAAC,EAAE,CAACH,IAAI,KAAKE;QAClC,MAAMM,SAA8C,CAAC;QACrD,IAAID,MAAMC,OAAOC,OAAO,GAAGF;QAC3B,IAAIF,MAAMG,OAAOH,IAAI,GAAGA;QACxB,OAAOG;IACT;IACA,MAAME,SAAShB,cAAcC;IAC7B,IAAIe,MAAM,CAAC,EAAE,EAAE,OAAO;QAAED,SAASC,MAAM,CAAC,EAAE;IAAC;IAC3C,OAAO;QAAED,SAASd,OAAOK,IAAI;IAAG;AAClC"}

package/dist/esm/email/parsing/html-processing.d.ts

@@ -0,0 +1,8 @@
+import type { gmail_v1 } from 'googleapis';
+export interface BodyExtractionOptions {
+    /** Format to return: 'text' extracts plain text, 'html' preserves HTML structure */
+    contentType?: 'text' | 'html';
+    /** When true, removes quoted thread history from HTML content */
+    excludeThreadHistory?: boolean;
+}
+export declare function extractBodyFromPayload(payload: gmail_v1.Schema$MessagePart, options?: BodyExtractionOptions): string;

package/dist/esm/email/parsing/html-processing.js

@@ -0,0 +1,39 @@
+import { extractCurrentMessageFromHtml } from '@mcp-z/email';
+import { parse } from 'node-html-parser';
+export function extractBodyFromPayload(payload, options = {}) {
+    var _payload_body;
+    const { contentType = 'text', excludeThreadHistory = false } = options;
+    if (!payload) return '';
+    // If there's a direct body with data
+    if ((_payload_body = payload.body) === null || _payload_body === void 0 ? void 0 : _payload_body.data) {
+        return Buffer.from(payload.body.data, 'base64').toString('utf-8');
+    }
+    // If there are parts, look for text/plain or text/html
+    if (payload.parts && Array.isArray(payload.parts)) {
+        for (const part of payload.parts){
+            var _part_body, _part_body1;
+            if (part.mimeType === 'text/plain' && ((_part_body = part.body) === null || _part_body === void 0 ? void 0 : _part_body.data)) {
+                return Buffer.from(part.body.data, 'base64').toString('utf-8');
+            }
+            if (part.mimeType === 'text/html' && ((_part_body1 = part.body) === null || _part_body1 === void 0 ? void 0 : _part_body1.data)) {
+                let html = Buffer.from(part.body.data, 'base64').toString('utf-8');
+                // Remove thread history if requested
+                if (excludeThreadHistory) {
+                    html = extractCurrentMessageFromHtml(html);
+                }
+                // Return HTML directly if requested
+                if (contentType === 'html') {
+                    return html;
+                }
+                // Otherwise extract plain text from HTML
+                const doc = parse(html);
+                const docUnknown = doc;
+                if (docUnknown && typeof docUnknown === 'object' && 'text' in docUnknown) {
+                    return docUnknown.text;
+                }
+                return '';
+            }
+        }
+    }
+    return '';
+}

package/dist/esm/email/parsing/html-processing.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["/Users/kevin/Dev/Projects/ai/mcp-z/servers/mcp-gmail/src/email/parsing/html-processing.ts"],"sourcesContent":["import { extractCurrentMessageFromHtml } from '@mcp-z/email';\nimport type { gmail_v1 } from 'googleapis';\nimport { parse } from 'node-html-parser';\n\nexport interface BodyExtractionOptions {\n  /** Format to return: 'text' extracts plain text, 'html' preserves HTML structure */\n  contentType?: 'text' | 'html';\n  /** When true, removes quoted thread history from HTML content */\n  excludeThreadHistory?: boolean;\n}\n\nexport function extractBodyFromPayload(payload: gmail_v1.Schema$MessagePart, options: BodyExtractionOptions = {}): string {\n  const { contentType = 'text', excludeThreadHistory = false } = options;\n  if (!payload) return '';\n\n  // If there's a direct body with data\n  if (payload.body?.data) {\n    return Buffer.from(payload.body.data, 'base64').toString('utf-8');\n  }\n\n  // If there are parts, look for text/plain or text/html\n  if (payload.parts && Array.isArray(payload.parts)) {\n    for (const part of payload.parts) {\n      if (part.mimeType === 'text/plain' && part.body?.data) {\n        return Buffer.from(part.body.data, 'base64').toString('utf-8');\n      }\n      if (part.mimeType === 'text/html' && part.body?.data) {\n        let html = Buffer.from(part.body.data, 'base64').toString('utf-8');\n\n        // Remove thread history if requested\n        if (excludeThreadHistory) {\n          html = extractCurrentMessageFromHtml(html);\n        }\n\n        // Return HTML directly if requested\n        if (contentType === 'html') {\n          return html;\n        }\n\n        // Otherwise extract plain text from HTML\n        const doc = parse(html);\n        const docUnknown = doc as unknown;\n        if (docUnknown && typeof docUnknown === 'object' && 'text' in docUnknown) {\n          return docUnknown.text as string;\n        }\n        return '';\n      }\n    }\n  }\n\n  return '';\n}\n"],"names":["extractCurrentMessageFromHtml","parse","extractBodyFromPayload","payload","options","contentType","excludeThreadHistory","body","data","Buffer","from","toString","parts","Array","isArray","part","mimeType","html","doc","docUnknown","text"],"mappings":"AAAA,SAASA,6BAA6B,QAAQ,eAAe;AAE7D,SAASC,KAAK,QAAQ,mBAAmB;AASzC,OAAO,SAASC,uBAAuBC,OAAoC,EAAEC,UAAiC,CAAC,CAAC;QAK1GD;IAJJ,MAAM,EAAEE,cAAc,MAAM,EAAEC,uBAAuB,KAAK,EAAE,GAAGF;IAC/D,IAAI,CAACD,SAAS,OAAO;IAErB,qCAAqC;IACrC,KAAIA,gBAAAA,QAAQI,IAAI,cAAZJ,oCAAAA,cAAcK,IAAI,EAAE;QACtB,OAAOC,OAAOC,IAAI,CAACP,QAAQI,IAAI,CAACC,IAAI,EAAE,UAAUG,QAAQ,CAAC;IAC3D;IAEA,uDAAuD;IACvD,IAAIR,QAAQS,KAAK,IAAIC,MAAMC,OAAO,CAACX,QAAQS,KAAK,GAAG;QACjD,KAAK,MAAMG,QAAQZ,QAAQS,KAAK,CAAE;gBACMG,YAGDA;YAHrC,IAAIA,KAAKC,QAAQ,KAAK,kBAAgBD,aAAAA,KAAKR,IAAI,cAATQ,iCAAAA,WAAWP,IAAI,GAAE;gBACrD,OAAOC,OAAOC,IAAI,CAACK,KAAKR,IAAI,CAACC,IAAI,EAAE,UAAUG,QAAQ,CAAC;YACxD;YACA,IAAII,KAAKC,QAAQ,KAAK,iBAAeD,cAAAA,KAAKR,IAAI,cAATQ,kCAAAA,YAAWP,IAAI,GAAE;gBACpD,IAAIS,OAAOR,OAAOC,IAAI,CAACK,KAAKR,IAAI,CAACC,IAAI,EAAE,UAAUG,QAAQ,CAAC;gBAE1D,qCAAqC;gBACrC,IAAIL,sBAAsB;oBACxBW,OAAOjB,8BAA8BiB;gBACvC;gBAEA,oCAAoC;gBACpC,IAAIZ,gBAAgB,QAAQ;oBAC1B,OAAOY;gBACT;gBAEA,yCAAyC;gBACzC,MAAMC,MAAMjB,MAAMgB;gBAClB,MAAME,aAAaD;gBACnB,IAAIC,cAAc,OAAOA,eAAe,YAAY,UAAUA,YAAY;oBACxE,OAAOA,WAAWC,IAAI;gBACxB;gBACA,OAAO;YACT;QACF;IACF;IAEA,OAAO;AACT"}

package/dist/esm/email/parsing/message-extraction.d.ts

@@ -0,0 +1,2 @@
+export { extractEmails, extractFrom } from './headers-utils.js';
+export { extractBodyFromPayload } from './html-processing.js';

package/dist/esm/email/parsing/message-extraction.js

@@ -0,0 +1,3 @@
+// Unified message extraction functionality
+export { extractEmails, extractFrom } from './headers-utils.js';
+export { extractBodyFromPayload } from './html-processing.js';

package/dist/esm/email/parsing/message-extraction.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["/Users/kevin/Dev/Projects/ai/mcp-z/servers/mcp-gmail/src/email/parsing/message-extraction.ts"],"sourcesContent":["// Unified message extraction functionality\n\nexport { extractEmails, extractFrom } from './headers-utils.js';\nexport { extractBodyFromPayload } from './html-processing.js';\n"],"names":["extractEmails","extractFrom","extractBodyFromPayload"],"mappings":"AAAA,2CAA2C;AAE3C,SAASA,aAAa,EAAEC,WAAW,QAAQ,qBAAqB;AAChE,SAASC,sBAAsB,QAAQ,uBAAuB"}

package/dist/esm/email/querying/execute-query.d.ts

@@ -0,0 +1,17 @@
+import type { ExecutionResult } from '@mcp-z/email';
+import type { gmail_v1 } from 'googleapis';
+import type { GmailQuery as QueryNode } from '../../schemas/gmail-query-schema.js';
+import type { Logger } from '../../types.js';
+export interface ExecuteQueryOptions {
+    client: gmail_v1.Gmail;
+    logger: Logger;
+    pageSize?: number;
+    pageToken?: string;
+    includeBody?: boolean;
+}
+/**
+ * Execute a Gmail query with direct, single-attempt execution.
+ * No planning, no fallbacks, no retries.
+ * Provider errors are returned directly to the caller for actionable feedback.
+ */
+export declare function executeQuery<T>(query: QueryNode | undefined, options: ExecuteQueryOptions, transform: (item: unknown) => T): Promise<ExecutionResult<T>>;

package/dist/esm/email/querying/execute-query.js

@@ -0,0 +1,45 @@
+import { MAX_PAGE_SIZE } from '../../constants.js';
+import { searchMessages } from './search-execution.js';
+/**
+ * Execute a Gmail query with direct, single-attempt execution.
+ * No planning, no fallbacks, no retries.
+ * Provider errors are returned directly to the caller for actionable feedback.
+ */ export async function executeQuery(query, options, transform) {
+    const { client, logger, pageSize, pageToken, includeBody } = options;
+    // Validate pagination parameters
+    if (pageSize !== undefined && (pageSize < 1 || pageSize > MAX_PAGE_SIZE)) {
+        throw new Error(`pageSize must be between 1 and ${MAX_PAGE_SIZE}`);
+    }
+    if (pageToken !== undefined && typeof pageToken === 'string' && pageToken.trim().length === 0) {
+        logger.info('Empty pageToken provided, ignoring');
+    }
+    // Single execution - direct query to Gmail API
+    logger.info('executeQuery: executing direct Gmail query');
+    try {
+        const result = await searchMessages(client, {
+            ...query !== undefined && {
+                query
+            },
+            pageSize: pageSize !== null && pageSize !== void 0 ? pageSize : 50,
+            pageToken: pageToken && pageToken.trim().length > 0 ? pageToken : undefined,
+            includeBody: includeBody !== null && includeBody !== void 0 ? includeBody : false,
+            logger
+        });
+        // Transform results
+        const transformedResults = result.messages.map(transform);
+        logger.info(`executeQuery: succeeded with ${transformedResults.length} results`);
+        return {
+            success: true,
+            items: transformedResults,
+            metadata: {
+                nextPageToken: result.nextPageToken
+            }
+        };
+    } catch (error) {
+        // Re-throw errors directly - no fallback logic
+        logger.error('executeQuery: failed', {
+            error: error instanceof Error ? error.message : String(error)
+        });
+        throw error;
+    }
+}

package/dist/esm/email/querying/execute-query.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["/Users/kevin/Dev/Projects/ai/mcp-z/servers/mcp-gmail/src/email/querying/execute-query.ts"],"sourcesContent":["import type { ExecutionResult } from '@mcp-z/email';\nimport type { gmail_v1 } from 'googleapis';\nimport { MAX_PAGE_SIZE } from '../../constants.ts';\nimport type { GmailQuery as QueryNode } from '../../schemas/gmail-query-schema.js';\nimport type { Logger } from '../../types.js';\nimport { searchMessages } from './search-execution.js';\n\nexport interface ExecuteQueryOptions {\n  client: gmail_v1.Gmail;\n  logger: Logger;\n  pageSize?: number;\n  pageToken?: string;\n  includeBody?: boolean;\n}\n\n/**\n * Execute a Gmail query with direct, single-attempt execution.\n * No planning, no fallbacks, no retries.\n * Provider errors are returned directly to the caller for actionable feedback.\n */\nexport async function executeQuery<T>(query: QueryNode | undefined, options: ExecuteQueryOptions, transform: (item: unknown) => T): Promise<ExecutionResult<T>> {\n  const { client, logger, pageSize, pageToken, includeBody } = options;\n\n  // Validate pagination parameters\n  if (pageSize !== undefined && (pageSize < 1 || pageSize > MAX_PAGE_SIZE)) {\n    throw new Error(`pageSize must be between 1 and ${MAX_PAGE_SIZE}`);\n  }\n\n  if (pageToken !== undefined && typeof pageToken === 'string' && pageToken.trim().length === 0) {\n    logger.info('Empty pageToken provided, ignoring');\n  }\n\n  // Single execution - direct query to Gmail API\n  logger.info('executeQuery: executing direct Gmail query');\n\n  try {\n    const result = await searchMessages(client, {\n      ...(query !== undefined && { query }),\n      pageSize: pageSize ?? 50,\n      pageToken: pageToken && pageToken.trim().length > 0 ? pageToken : undefined,\n      includeBody: includeBody ?? false,\n      logger,\n    });\n\n    // Transform results\n    const transformedResults = result.messages.map(transform);\n\n    logger.info(`executeQuery: succeeded with ${transformedResults.length} results`);\n\n    return {\n      success: true,\n      items: transformedResults,\n      metadata: {\n        nextPageToken: result.nextPageToken,\n      },\n    };\n  } catch (error) {\n    // Re-throw errors directly - no fallback logic\n    logger.error('executeQuery: failed', { error: error instanceof Error ? error.message : String(error) });\n    throw error;\n  }\n}\n"],"names":["MAX_PAGE_SIZE","searchMessages","executeQuery","query","options","transform","client","logger","pageSize","pageToken","includeBody","undefined","Error","trim","length","info","result","transformedResults","messages","map","success","items","metadata","nextPageToken","error","message","String"],"mappings":"AAEA,SAASA,aAAa,QAAQ,qBAAqB;AAGnD,SAASC,cAAc,QAAQ,wBAAwB;AAUvD;;;;CAIC,GACD,OAAO,eAAeC,aAAgBC,KAA4B,EAAEC,OAA4B,EAAEC,SAA+B;IAC/H,MAAM,EAAEC,MAAM,EAAEC,MAAM,EAAEC,QAAQ,EAAEC,SAAS,EAAEC,WAAW,EAAE,GAAGN;IAE7D,iCAAiC;IACjC,IAAII,aAAaG,aAAcH,CAAAA,WAAW,KAAKA,WAAWR,aAAY,GAAI;QACxE,MAAM,IAAIY,MAAM,CAAC,+BAA+B,EAAEZ,eAAe;IACnE;IAEA,IAAIS,cAAcE,aAAa,OAAOF,cAAc,YAAYA,UAAUI,IAAI,GAAGC,MAAM,KAAK,GAAG;QAC7FP,OAAOQ,IAAI,CAAC;IACd;IAEA,+CAA+C;IAC/CR,OAAOQ,IAAI,CAAC;IAEZ,IAAI;QACF,MAAMC,SAAS,MAAMf,eAAeK,QAAQ;YAC1C,GAAIH,UAAUQ,aAAa;gBAAER;YAAM,CAAC;YACpCK,QAAQ,EAAEA,qBAAAA,sBAAAA,WAAY;YACtBC,WAAWA,aAAaA,UAAUI,IAAI,GAAGC,MAAM,GAAG,IAAIL,YAAYE;YAClED,WAAW,EAAEA,wBAAAA,yBAAAA,cAAe;YAC5BH;QACF;QAEA,oBAAoB;QACpB,MAAMU,qBAAqBD,OAAOE,QAAQ,CAACC,GAAG,CAACd;QAE/CE,OAAOQ,IAAI,CAAC,CAAC,6BAA6B,EAAEE,mBAAmBH,MAAM,CAAC,QAAQ,CAAC;QAE/E,OAAO;YACLM,SAAS;YACTC,OAAOJ;YACPK,UAAU;gBACRC,eAAeP,OAAOO,aAAa;YACrC;QACF;IACF,EAAE,OAAOC,OAAO;QACd,+CAA+C;QAC/CjB,OAAOiB,KAAK,CAAC,wBAAwB;YAAEA,OAAOA,iBAAiBZ,QAAQY,MAAMC,OAAO,GAAGC,OAAOF;QAAO;QACrG,MAAMA;IACR;AACF"}

package/dist/esm/email/querying/pagination.d.ts

@@ -0,0 +1,27 @@
+/** Gmail pagination helpers for single-page operations. */
+import type { gmail_v1 } from 'googleapis';
+import type { Logger } from '../../types.js';
+export interface SinglePageResult {
+    readonly messages: gmail_v1.Schema$Message[];
+    readonly nextPageToken: string | undefined;
+}
+/**
+ * Fetch a single page of messages from Gmail
+ */
+export interface FetchMessagesPageParams {
+    readonly gmailQ: string;
+    readonly pageSize?: number;
+    readonly pageToken: string | undefined;
+    readonly body?: boolean;
+    readonly logger: Logger;
+    readonly metadataHeaders?: readonly string[];
+}
+export declare function fetchMessagesPage(gmail: gmail_v1.Gmail, params: FetchMessagesPageParams): Promise<SinglePageResult>;
+export interface FetchMessagesConcurrentlyParams {
+    readonly items: readonly string[];
+    readonly concurrency?: number;
+    readonly body?: boolean;
+    readonly logger: Logger;
+    readonly metadataHeaders?: readonly string[];
+}
+export declare function fetchMessagesConcurrently(gmail: gmail_v1.Gmail, params: FetchMessagesConcurrentlyParams): Promise<gmail_v1.Schema$Message[]>;

package/dist/esm/email/querying/pagination.js

@@ -0,0 +1,152 @@
+/** Gmail pagination helpers for single-page operations. */ export async function fetchMessagesPage(gmail, params) {
+    const { gmailQ, pageSize = 50, pageToken, body = false, logger, metadataHeaders } = params;
+    // Secure resource bounds checking - prevent security bypasses
+    const maxPageSize = 500; // Gmail API maximum - enforced for security
+    const minPageSize = 1; // Minimum valid page size
+    // Validate input is a positive number to prevent bypass attempts
+    if (!Number.isInteger(pageSize) || pageSize < 0) {
+        throw new Error(`Invalid pageSize: must be a positive integer, got ${pageSize}`);
+    }
+    const safePageSize = Math.min(Math.max(minPageSize, pageSize), maxPageSize);
+    if (pageSize !== safePageSize && logger) {
+        logger.info('Page size bounded for API safety', {
+            requested: pageSize,
+            applied: safePageSize
+        });
+    // No fallback to console - would corrupt MCP stdio communication
+    }
+    try {
+        const listParams = {
+            userId: 'me',
+            q: gmailQ,
+            maxResults: safePageSize
+        };
+        const listResponse = pageToken && pageToken.trim().length > 0 ? await gmail.users.messages.list({
+            ...listParams,
+            pageToken
+        }) : await gmail.users.messages.list(listParams);
+        const response = listResponse.data;
+        const messages = response.messages || [];
+        if (messages.length === 0) {
+            if (logger) logger.info('No messages found on page');
+            return {
+                messages: [],
+                nextPageToken: undefined
+            };
+        }
+        const items = messages.map((m)=>m.id).filter(Boolean);
+        if (items.length === 0) {
+            if (logger) logger.info('No valid message ids on page');
+            return {
+                messages: [],
+                nextPageToken: response.nextPageToken && response.nextPageToken.trim().length > 0 ? response.nextPageToken : undefined
+            };
+        }
+        const concurrentArgs = {
+            items,
+            concurrency: 5,
+            body,
+            ...logger && {
+                logger
+            },
+            ...metadataHeaders && {
+                metadataHeaders
+            }
+        };
+        const detailedMessages = await fetchMessagesConcurrently(gmail, concurrentArgs);
+        if (logger) logger.info(`Fetched page with ${detailedMessages.length} messages`);
+        return {
+            messages: detailedMessages,
+            nextPageToken: response.nextPageToken && response.nextPageToken.trim().length > 0 ? response.nextPageToken : undefined
+        };
+    } catch (error) {
+        // Standardized error handling for pagination pipeline
+        const errorMessage = error instanceof Error ? error.message : String(error);
+        if (logger) logger.error('Gmail pagination: single page fetch failed', {
+            error: errorMessage,
+            query: gmailQ,
+            pageSize: safePageSize,
+            hasPageToken: !!pageToken
+        });
+        // Preserve original error type for upstream handling
+        if (error instanceof Error) {
+            // Enhance error with pagination context
+            error.message = `Gmail pagination fetch failed: ${error.message}`;
+            throw error;
+        }
+        // Convert non-Error objects to proper Error instances
+        throw new Error(`Gmail pagination fetch failed: ${errorMessage}`);
+    }
+}
+export async function fetchMessagesConcurrently(gmail, params) {
+    const { items, concurrency = 2, body = false, logger, metadataHeaders } = params;
+    // Secure resource bounds checking for concurrent operations
+    const maxConcurrency = 10; // Conservative limit to prevent rate limiting and resource exhaustion
+    const minConcurrency = 1; // Minimum valid concurrency
+    // Validate input is a positive number to prevent bypass attempts
+    if (!Number.isInteger(concurrency) || concurrency < 0) {
+        throw new Error(`Invalid concurrency: must be a positive integer, got ${concurrency}`);
+    }
+    const safeConcurrency = Math.min(Math.max(minConcurrency, concurrency), maxConcurrency);
+    if (concurrency !== safeConcurrency && logger) {
+        logger.info('Concurrency bounded for API safety', {
+            requested: concurrency,
+            applied: safeConcurrency
+        });
+    // No fallback to console - would corrupt MCP stdio communication
+    }
+    if (items.length === 0) return [];
+    const results = new Array(items.length);
+    const format = body ? 'full' : 'metadata';
+    // Always pass metadataHeaders if provided - body doesn't replace headers, it's additional content
+    const metadataHeadersForRequest = metadataHeaders;
+    // Pre-build request parameters to avoid repeated object creation
+    const requestParams = items.map((id)=>{
+        const baseParams = {
+            userId: 'me',
+            id,
+            format
+        };
+        // Only include metadataHeaders if defined (exactOptionalPropertyTypes compliance)
+        return metadataHeadersForRequest ? {
+            ...baseParams,
+            metadataHeaders: [
+                ...metadataHeadersForRequest
+            ]
+        } : baseParams;
+    });
+    // Optimize concurrent processing using batching
+    const batchSize = safeConcurrency;
+    const batches = [];
+    for(let i = 0; i < requestParams.length; i += batchSize){
+        batches.push(requestParams.slice(i, i + batchSize));
+    }
+    let processedCount = 0;
+    for (const batch of batches){
+        const batchPromises = batch.map(async (params, batchIndex)=>{
+            try {
+                const messageResponse = await gmail.users.messages.get(params);
+                const globalIndex = processedCount + batchIndex;
+                results[globalIndex] = messageResponse.data;
+                return messageResponse.data;
+            } catch (error) {
+                // Log individual message fetch failures but continue processing
+                const errorMessage = error instanceof Error ? error.message : String(error);
+                if (logger) logger.info('Gmail pagination: individual message fetch failed, continuing', {
+                    error: errorMessage,
+                    messageId: params.id,
+                    globalIndex: processedCount + batchIndex
+                });
+                return null; // Mark as failed but continue
+            }
+        });
+        await Promise.all(batchPromises);
+        processedCount += batch.length;
+        // Progress logging for large batches
+        if (items.length > 20) {
+            if (logger) logger.info(`Gmail pagination: processed ${processedCount}/${items.length} messages`);
+        }
+    }
+    // Filter out any null results from failed individual fetches
+    return results.filter((result)=>result !== null && result !== undefined);
+}

package/dist/esm/email/querying/pagination.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["/Users/kevin/Dev/Projects/ai/mcp-z/servers/mcp-gmail/src/email/querying/pagination.ts"],"sourcesContent":["/** Gmail pagination helpers for single-page operations. */\n\nimport type { gmail_v1 } from 'googleapis';\nimport type { Logger } from '../../types.js';\n\nexport interface SinglePageResult {\n  readonly messages: gmail_v1.Schema$Message[];\n  readonly nextPageToken: string | undefined;\n}\n\n/**\n * Fetch a single page of messages from Gmail\n */\nexport interface FetchMessagesPageParams {\n  readonly gmailQ: string;\n  readonly pageSize?: number;\n  readonly pageToken: string | undefined;\n  readonly body?: boolean;\n  readonly logger: Logger;\n  readonly metadataHeaders?: readonly string[];\n}\n\nexport async function fetchMessagesPage(gmail: gmail_v1.Gmail, params: FetchMessagesPageParams): Promise<SinglePageResult> {\n  const { gmailQ, pageSize = 50, pageToken, body = false, logger, metadataHeaders } = params;\n\n  // Secure resource bounds checking - prevent security bypasses\n  const maxPageSize = 500; // Gmail API maximum - enforced for security\n  const minPageSize = 1; // Minimum valid page size\n\n  // Validate input is a positive number to prevent bypass attempts\n  if (!Number.isInteger(pageSize) || pageSize < 0) {\n    throw new Error(`Invalid pageSize: must be a positive integer, got ${pageSize}`);\n  }\n\n  const safePageSize = Math.min(Math.max(minPageSize, pageSize), maxPageSize);\n\n  if (pageSize !== safePageSize && logger) {\n    logger.info('Page size bounded for API safety', { requested: pageSize, applied: safePageSize });\n    // No fallback to console - would corrupt MCP stdio communication\n  }\n\n  try {\n    const listParams = {\n      userId: 'me',\n      q: gmailQ,\n      maxResults: safePageSize,\n    };\n    const listResponse = pageToken && pageToken.trim().length > 0 ? await gmail.users.messages.list({ ...listParams, pageToken }) : await gmail.users.messages.list(listParams);\n    const response = listResponse.data;\n    const messages = response.messages || [];\n\n    if (messages.length === 0) {\n      if (logger) logger.info('No messages found on page');\n      return { messages: [], nextPageToken: undefined };\n    }\n\n    const items = messages.map((m: gmail_v1.Schema$Message) => m.id).filter(Boolean) as string[];\n    if (items.length === 0) {\n      if (logger) logger.info('No valid message ids on page');\n      return { messages: [], nextPageToken: response.nextPageToken && response.nextPageToken.trim().length > 0 ? response.nextPageToken : undefined };\n    }\n\n    const concurrentArgs: FetchMessagesConcurrentlyParams = {\n      items,\n      concurrency: 5,\n      body,\n      ...(logger && { logger }),\n      ...(metadataHeaders && { metadataHeaders }),\n    };\n    const detailedMessages = await fetchMessagesConcurrently(gmail, concurrentArgs);\n\n    if (logger) logger.info(`Fetched page with ${detailedMessages.length} messages`);\n    return {\n      messages: detailedMessages,\n      nextPageToken: response.nextPageToken && response.nextPageToken.trim().length > 0 ? response.nextPageToken : undefined,\n    };\n  } catch (error) {\n    // Standardized error handling for pagination pipeline\n    const errorMessage = error instanceof Error ? error.message : String(error);\n    if (logger)\n      logger.error('Gmail pagination: single page fetch failed', {\n        error: errorMessage,\n        query: gmailQ,\n        pageSize: safePageSize,\n        hasPageToken: !!pageToken,\n      });\n\n    // Preserve original error type for upstream handling\n    if (error instanceof Error) {\n      // Enhance error with pagination context\n      error.message = `Gmail pagination fetch failed: ${error.message}`;\n      throw error;\n    }\n\n    // Convert non-Error objects to proper Error instances\n    throw new Error(`Gmail pagination fetch failed: ${errorMessage}`);\n  }\n}\n\nexport interface FetchMessagesConcurrentlyParams {\n  readonly items: readonly string[];\n  readonly concurrency?: number;\n  readonly body?: boolean;\n  readonly logger: Logger;\n  readonly metadataHeaders?: readonly string[];\n}\n\nexport async function fetchMessagesConcurrently(gmail: gmail_v1.Gmail, params: FetchMessagesConcurrentlyParams): Promise<gmail_v1.Schema$Message[]> {\n  const { items, concurrency = 2, body = false, logger, metadataHeaders } = params;\n\n  // Secure resource bounds checking for concurrent operations\n  const maxConcurrency = 10; // Conservative limit to prevent rate limiting and resource exhaustion\n  const minConcurrency = 1; // Minimum valid concurrency\n\n  // Validate input is a positive number to prevent bypass attempts\n  if (!Number.isInteger(concurrency) || concurrency < 0) {\n    throw new Error(`Invalid concurrency: must be a positive integer, got ${concurrency}`);\n  }\n\n  const safeConcurrency = Math.min(Math.max(minConcurrency, concurrency), maxConcurrency);\n\n  if (concurrency !== safeConcurrency && logger) {\n    logger.info('Concurrency bounded for API safety', { requested: concurrency, applied: safeConcurrency });\n    // No fallback to console - would corrupt MCP stdio communication\n  }\n\n  if (items.length === 0) return [];\n\n  const results: (gmail_v1.Schema$Message | null)[] = new Array(items.length);\n  const format = body ? 'full' : 'metadata';\n  // Always pass metadataHeaders if provided - body doesn't replace headers, it's additional content\n  const metadataHeadersForRequest = metadataHeaders;\n\n  // Pre-build request parameters to avoid repeated object creation\n  const requestParams = items.map((id) => {\n    const baseParams = {\n      userId: 'me' as const,\n      id,\n      format,\n    };\n    // Only include metadataHeaders if defined (exactOptionalPropertyTypes compliance)\n    return metadataHeadersForRequest ? { ...baseParams, metadataHeaders: [...metadataHeadersForRequest] } : baseParams;\n  });\n\n  // Optimize concurrent processing using batching\n  const batchSize = safeConcurrency;\n  const batches: (typeof requestParams)[] = [];\n  for (let i = 0; i < requestParams.length; i += batchSize) {\n    batches.push(requestParams.slice(i, i + batchSize));\n  }\n\n  let processedCount = 0;\n  for (const batch of batches) {\n    const batchPromises = batch.map(async (params, batchIndex) => {\n      try {\n        const messageResponse = await gmail.users.messages.get(params);\n        const globalIndex = processedCount + batchIndex;\n        results[globalIndex] = messageResponse.data;\n        return messageResponse.data;\n      } catch (error) {\n        // Log individual message fetch failures but continue processing\n        const errorMessage = error instanceof Error ? error.message : String(error);\n        if (logger)\n          logger.info('Gmail pagination: individual message fetch failed, continuing', {\n            error: errorMessage,\n            messageId: params.id,\n            globalIndex: processedCount + batchIndex,\n          });\n        return null; // Mark as failed but continue\n      }\n    });\n\n    await Promise.all(batchPromises);\n    processedCount += batch.length;\n\n    // Progress logging for large batches\n    if (items.length > 20) {\n      if (logger) logger.info(`Gmail pagination: processed ${processedCount}/${items.length} messages`);\n    }\n  }\n\n  // Filter out any null results from failed individual fetches\n  return results.filter((result) => result !== null && result !== undefined);\n}\n"],"names":["fetchMessagesPage","gmail","params","gmailQ","pageSize","pageToken","body","logger","metadataHeaders","maxPageSize","minPageSize","Number","isInteger","Error","safePageSize","Math","min","max","info","requested","applied","listParams","userId","q","maxResults","listResponse","trim","length","users","messages","list","response","data","nextPageToken","undefined","items","map","m","id","filter","Boolean","concurrentArgs","concurrency","detailedMessages","fetchMessagesConcurrently","error","errorMessage","message","String","query","hasPageToken","maxConcurrency","minConcurrency","safeConcurrency","results","Array","format","metadataHeadersForRequest","requestParams","baseParams","batchSize","batches","i","push","slice","processedCount","batch","batchPromises","batchIndex","messageResponse","get","globalIndex","messageId","Promise","all","result"],"mappings":"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"}

package/dist/esm/email/querying/query-builder.d.ts

@@ -0,0 +1,47 @@
+import type { GmailQuery as QueryNode } from '../../schemas/gmail-query-schema.js';
+/**
+ * Field operator interface for query filters
+ */
+export interface FieldOperator {
+    $any?: string[];
+    $all?: string[];
+    $none?: string[];
+}
+/**
+ * Field query interface with support for all email fields including categories and labels
+ */
+export interface FieldQuery {
+    from?: FieldOperator | string;
+    to?: FieldOperator | string;
+    cc?: FieldOperator | string;
+    bcc?: FieldOperator | string;
+    subject?: FieldOperator | string;
+    text?: FieldOperator | string;
+    body?: FieldOperator | string;
+    categories?: FieldOperator | string;
+    label?: FieldOperator | string;
+}
+/**
+ * Filter extraction result with all collected values from a query
+ */
+export interface Filters {
+    subjectIncludes?: string[];
+    bodyIncludes?: string[];
+    textIncludes?: string[];
+    fromIncludes?: string[];
+    toIncludes?: string[];
+    ccIncludes?: string[];
+    bccIncludes?: string[];
+    categoriesIncludes?: string[];
+    labelIncludes?: string[];
+    hasAttachment?: boolean;
+    since?: string;
+    before?: string;
+}
+export declare function toGmailQuery(query: QueryNode, options?: {
+    dateSlash?: boolean;
+}): {
+    q: string;
+    filters: Record<string, unknown>;
+};
+export declare function extractFiltersFromParsed(parsed: QueryNode): Filters;