@mcp-z/mcp-gmail 1.0.0

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

@@ -0,0 +1,46 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", {
+    value: true
+});
+function _export(target, all) {
+    for(var name in all)Object.defineProperty(target, name, {
+        enumerable: true,
+        get: Object.getOwnPropertyDescriptor(all, name).get
+    });
+}
+_export(exports, {
+    get extractEmails () {
+        return extractEmails;
+    },
+    get extractFrom () {
+        return extractFrom;
+    }
+});
+function extractEmails(header) {
+    if (!header) return [];
+    var matches = header.match(/[A-Z0-9._%+-]+@[A-Z0-9.-]+\.[A-Z]{2,}/gi) || [];
+    return matches.map(function(s) {
+        return s.trim();
+    });
+}
+function extractFrom(header) {
+    if (!header) return undefined;
+    var m = header.match(/^(.*)<([^>]+)>/);
+    if (m) {
+        var rawName = m[1];
+        var name = rawName ? rawName.replace(/"/g, '').trim() : undefined;
+        var addr = m[2] ? m[2].trim() : undefined;
+        var result = {};
+        if (addr) result.address = addr;
+        if (name) result.name = name;
+        return result;
+    }
+    var emails = extractEmails(header);
+    if (emails[0]) return {
+        address: emails[0]
+    };
+    return {
+        address: header.trim()
+    };
+}
+/* CJS INTEROP */ if (exports.__esModule && exports.default) { try { Object.defineProperty(exports.default, '__esModule', { value: true }); for (var key in exports) { exports.default[key] = exports[key]; } } catch (_) {}; module.exports = exports.default; }

package/dist/cjs/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","extractFrom","header","matches","match","map","s","trim","undefined","m","rawName","name","replace","addr","result","address","emails"],"mappings":";;;;;;;;;;;QAAgBA;eAAAA;;QAMAC;eAAAA;;;AANT,SAASD,cAAcE,MAAe;IAC3C,IAAI,CAACA,QAAQ,OAAO,EAAE;IACtB,IAAMC,UAAUD,OAAOE,KAAK,CAAC,8CAA8C,EAAE;IAC7E,OAAOD,QAAQE,GAAG,CAAC,SAACC;eAAcA,EAAEC,IAAI;;AAC1C;AAEO,SAASN,YAAYC,MAAe;IACzC,IAAI,CAACA,QAAQ,OAAOM;IACpB,IAAMC,IAAIP,OAAOE,KAAK,CAAC;IACvB,IAAIK,GAAG;QACL,IAAMC,UAAUD,CAAC,CAAC,EAAE;QACpB,IAAME,OAAOD,UAAUA,QAAQE,OAAO,CAAC,MAAM,IAAIL,IAAI,KAAKC;QAC1D,IAAMK,OAAOJ,CAAC,CAAC,EAAE,GAAGA,CAAC,CAAC,EAAE,CAACF,IAAI,KAAKC;QAClC,IAAMM,SAA8C,CAAC;QACrD,IAAID,MAAMC,OAAOC,OAAO,GAAGF;QAC3B,IAAIF,MAAMG,OAAOH,IAAI,GAAGA;QACxB,OAAOG;IACT;IACA,IAAME,SAAShB,cAAcE;IAC7B,IAAIc,MAAM,CAAC,EAAE,EAAE,OAAO;QAAED,SAASC,MAAM,CAAC,EAAE;IAAC;IAC3C,OAAO;QAAED,SAASb,OAAOK,IAAI;IAAG;AAClC"}

package/dist/cjs/email/parsing/html-processing.d.cts

@@ -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/cjs/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/cjs/email/parsing/html-processing.js

@@ -0,0 +1,72 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", {
+    value: true
+});
+Object.defineProperty(exports, "extractBodyFromPayload", {
+    enumerable: true,
+    get: function() {
+        return extractBodyFromPayload;
+    }
+});
+var _email = require("@mcp-z/email");
+var _nodehtmlparser = require("node-html-parser");
+function _type_of(obj) {
+    "@swc/helpers - typeof";
+    return obj && typeof Symbol !== "undefined" && obj.constructor === Symbol ? "symbol" : typeof obj;
+}
+function extractBodyFromPayload(payload) {
+    var options = arguments.length > 1 && arguments[1] !== void 0 ? arguments[1] : {};
+    var _payload_body;
+    var _options_contentType = options.contentType, contentType = _options_contentType === void 0 ? 'text' : _options_contentType, _options_excludeThreadHistory = options.excludeThreadHistory, excludeThreadHistory = _options_excludeThreadHistory === void 0 ? false : _options_excludeThreadHistory;
+    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)) {
+        var _iteratorNormalCompletion = true, _didIteratorError = false, _iteratorError = undefined;
+        try {
+            for(var _iterator = payload.parts[Symbol.iterator](), _step; !(_iteratorNormalCompletion = (_step = _iterator.next()).done); _iteratorNormalCompletion = true){
+                var part = _step.value;
+                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)) {
+                    var html = Buffer.from(part.body.data, 'base64').toString('utf-8');
+                    // Remove thread history if requested
+                    if (excludeThreadHistory) {
+                        html = (0, _email.extractCurrentMessageFromHtml)(html);
+                    }
+                    // Return HTML directly if requested
+                    if (contentType === 'html') {
+                        return html;
+                    }
+                    // Otherwise extract plain text from HTML
+                    var doc = (0, _nodehtmlparser.parse)(html);
+                    var docUnknown = doc;
+                    if (docUnknown && (typeof docUnknown === "undefined" ? "undefined" : _type_of(docUnknown)) === 'object' && 'text' in docUnknown) {
+                        return docUnknown.text;
+                    }
+                    return '';
+                }
+            }
+        } catch (err) {
+            _didIteratorError = true;
+            _iteratorError = err;
+        } finally{
+            try {
+                if (!_iteratorNormalCompletion && _iterator.return != null) {
+                    _iterator.return();
+                }
+            } finally{
+                if (_didIteratorError) {
+                    throw _iteratorError;
+                }
+            }
+        }
+    }
+    return '';
+}
+/* CJS INTEROP */ if (exports.__esModule && exports.default) { try { Object.defineProperty(exports.default, '__esModule', { value: true }); for (var key in exports) { exports.default[key] = exports[key]; } } catch (_) {}; module.exports = exports.default; }

package/dist/cjs/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":["extractBodyFromPayload","payload","options","contentType","excludeThreadHistory","body","data","Buffer","from","toString","parts","Array","isArray","part","mimeType","html","extractCurrentMessageFromHtml","doc","parse","docUnknown","text"],"mappings":";;;;+BAWgBA;;;eAAAA;;;qBAX8B;8BAExB;;;;;AASf,SAASA,uBAAuBC,OAAoC;QAAEC,UAAAA,iEAAiC,CAAC;QAKzGD;IAJJ,2BAA+DC,QAAvDC,aAAAA,gDAAc,+DAAyCD,QAAjCE,sBAAAA,kEAAuB;IACrD,IAAI,CAACH,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;YAC5C,kCAAA,2BAAA;;YAAL,QAAK,YAAcT,QAAQS,KAAK,qBAA3B,SAAA,6BAAA,QAAA,yBAAA,iCAA6B;gBAA7B,IAAMG,OAAN;oBACmCA,YAGDA;gBAHrC,IAAIA,KAAKC,QAAQ,KAAK,kBAAgBD,aAAAA,KAAKR,IAAI,cAATQ,iCAAAA,WAAWP,IAAI,GAAE;oBACrD,OAAOC,OAAOC,IAAI,CAACK,KAAKR,IAAI,CAACC,IAAI,EAAE,UAAUG,QAAQ,CAAC;gBACxD;gBACA,IAAII,KAAKC,QAAQ,KAAK,iBAAeD,cAAAA,KAAKR,IAAI,cAATQ,kCAAAA,YAAWP,IAAI,GAAE;oBACpD,IAAIS,OAAOR,OAAOC,IAAI,CAACK,KAAKR,IAAI,CAACC,IAAI,EAAE,UAAUG,QAAQ,CAAC;oBAE1D,qCAAqC;oBACrC,IAAIL,sBAAsB;wBACxBW,OAAOC,IAAAA,oCAA6B,EAACD;oBACvC;oBAEA,oCAAoC;oBACpC,IAAIZ,gBAAgB,QAAQ;wBAC1B,OAAOY;oBACT;oBAEA,yCAAyC;oBACzC,IAAME,MAAMC,IAAAA,qBAAK,EAACH;oBAClB,IAAMI,aAAaF;oBACnB,IAAIE,cAAc,CAAA,OAAOA,2CAAP,SAAOA,WAAS,MAAM,YAAY,UAAUA,YAAY;wBACxE,OAAOA,WAAWC,IAAI;oBACxB;oBACA,OAAO;gBACT;YACF;;YAzBK;YAAA;;;qBAAA,6BAAA;oBAAA;;;oBAAA;0BAAA;;;;IA0BP;IAEA,OAAO;AACT"}

package/dist/cjs/email/parsing/message-extraction.d.cts

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

package/dist/cjs/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/cjs/email/parsing/message-extraction.js

@@ -0,0 +1,25 @@
+// Unified message extraction functionality
+"use strict";
+Object.defineProperty(exports, "__esModule", {
+    value: true
+});
+function _export(target, all) {
+    for(var name in all)Object.defineProperty(target, name, {
+        enumerable: true,
+        get: Object.getOwnPropertyDescriptor(all, name).get
+    });
+}
+_export(exports, {
+    get extractBodyFromPayload () {
+        return _htmlprocessing.extractBodyFromPayload;
+    },
+    get extractEmails () {
+        return _headersutils.extractEmails;
+    },
+    get extractFrom () {
+        return _headersutils.extractFrom;
+    }
+});
+var _headersutils = require("./headers-utils.js");
+var _htmlprocessing = require("./html-processing.js");
+/* CJS INTEROP */ if (exports.__esModule && exports.default) { try { Object.defineProperty(exports.default, '__esModule', { value: true }); for (var key in exports) { exports.default[key] = exports[key]; } } catch (_) {}; module.exports = exports.default; }

package/dist/cjs/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":["extractBodyFromPayload","extractEmails","extractFrom"],"mappings":"AAAA,2CAA2C;;;;;;;;;;;;QAGlCA;eAAAA,sCAAsB;;QADtBC;eAAAA,2BAAa;;QAAEC;eAAAA,yBAAW;;;4BAAQ;8BACJ"}

package/dist/cjs/email/querying/execute-query.d.cts

@@ -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/cjs/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/cjs/email/querying/execute-query.js

@@ -0,0 +1,265 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", {
+    value: true
+});
+Object.defineProperty(exports, "executeQuery", {
+    enumerable: true,
+    get: function() {
+        return executeQuery;
+    }
+});
+var _constantsts = require("../../constants.js");
+var _searchexecution = require("./search-execution.js");
+function asyncGeneratorStep(gen, resolve, reject, _next, _throw, key, arg) {
+    try {
+        var info = gen[key](arg);
+        var value = info.value;
+    } catch (error) {
+        reject(error);
+        return;
+    }
+    if (info.done) {
+        resolve(value);
+    } else {
+        Promise.resolve(value).then(_next, _throw);
+    }
+}
+function _async_to_generator(fn) {
+    return function() {
+        var self = this, args = arguments;
+        return new Promise(function(resolve, reject) {
+            var gen = fn.apply(self, args);
+            function _next(value) {
+                asyncGeneratorStep(gen, resolve, reject, _next, _throw, "next", value);
+            }
+            function _throw(err) {
+                asyncGeneratorStep(gen, resolve, reject, _next, _throw, "throw", err);
+            }
+            _next(undefined);
+        });
+    };
+}
+function _define_property(obj, key, value) {
+    if (key in obj) {
+        Object.defineProperty(obj, key, {
+            value: value,
+            enumerable: true,
+            configurable: true,
+            writable: true
+        });
+    } else {
+        obj[key] = value;
+    }
+    return obj;
+}
+function _instanceof(left, right) {
+    if (right != null && typeof Symbol !== "undefined" && right[Symbol.hasInstance]) {
+        return !!right[Symbol.hasInstance](left);
+    } else {
+        return left instanceof right;
+    }
+}
+function _object_spread(target) {
+    for(var i = 1; i < arguments.length; i++){
+        var source = arguments[i] != null ? arguments[i] : {};
+        var ownKeys = Object.keys(source);
+        if (typeof Object.getOwnPropertySymbols === "function") {
+            ownKeys = ownKeys.concat(Object.getOwnPropertySymbols(source).filter(function(sym) {
+                return Object.getOwnPropertyDescriptor(source, sym).enumerable;
+            }));
+        }
+        ownKeys.forEach(function(key) {
+            _define_property(target, key, source[key]);
+        });
+    }
+    return target;
+}
+function ownKeys(object, enumerableOnly) {
+    var keys = Object.keys(object);
+    if (Object.getOwnPropertySymbols) {
+        var symbols = Object.getOwnPropertySymbols(object);
+        if (enumerableOnly) {
+            symbols = symbols.filter(function(sym) {
+                return Object.getOwnPropertyDescriptor(object, sym).enumerable;
+            });
+        }
+        keys.push.apply(keys, symbols);
+    }
+    return keys;
+}
+function _object_spread_props(target, source) {
+    source = source != null ? source : {};
+    if (Object.getOwnPropertyDescriptors) {
+        Object.defineProperties(target, Object.getOwnPropertyDescriptors(source));
+    } else {
+        ownKeys(Object(source)).forEach(function(key) {
+            Object.defineProperty(target, key, Object.getOwnPropertyDescriptor(source, key));
+        });
+    }
+    return target;
+}
+function _ts_generator(thisArg, body) {
+    var f, y, t, _ = {
+        label: 0,
+        sent: function() {
+            if (t[0] & 1) throw t[1];
+            return t[1];
+        },
+        trys: [],
+        ops: []
+    }, g = Object.create((typeof Iterator === "function" ? Iterator : Object).prototype), d = Object.defineProperty;
+    return d(g, "next", {
+        value: verb(0)
+    }), d(g, "throw", {
+        value: verb(1)
+    }), d(g, "return", {
+        value: verb(2)
+    }), typeof Symbol === "function" && d(g, Symbol.iterator, {
+        value: function() {
+            return this;
+        }
+    }), g;
+    function verb(n) {
+        return function(v) {
+            return step([
+                n,
+                v
+            ]);
+        };
+    }
+    function step(op) {
+        if (f) throw new TypeError("Generator is already executing.");
+        while(g && (g = 0, op[0] && (_ = 0)), _)try {
+            if (f = 1, y && (t = op[0] & 2 ? y["return"] : op[0] ? y["throw"] || ((t = y["return"]) && t.call(y), 0) : y.next) && !(t = t.call(y, op[1])).done) return t;
+            if (y = 0, t) op = [
+                op[0] & 2,
+                t.value
+            ];
+            switch(op[0]){
+                case 0:
+                case 1:
+                    t = op;
+                    break;
+                case 4:
+                    _.label++;
+                    return {
+                        value: op[1],
+                        done: false
+                    };
+                case 5:
+                    _.label++;
+                    y = op[1];
+                    op = [
+                        0
+                    ];
+                    continue;
+                case 7:
+                    op = _.ops.pop();
+                    _.trys.pop();
+                    continue;
+                default:
+                    if (!(t = _.trys, t = t.length > 0 && t[t.length - 1]) && (op[0] === 6 || op[0] === 2)) {
+                        _ = 0;
+                        continue;
+                    }
+                    if (op[0] === 3 && (!t || op[1] > t[0] && op[1] < t[3])) {
+                        _.label = op[1];
+                        break;
+                    }
+                    if (op[0] === 6 && _.label < t[1]) {
+                        _.label = t[1];
+                        t = op;
+                        break;
+                    }
+                    if (t && _.label < t[2]) {
+                        _.label = t[2];
+                        _.ops.push(op);
+                        break;
+                    }
+                    if (t[2]) _.ops.pop();
+                    _.trys.pop();
+                    continue;
+            }
+            op = body.call(thisArg, _);
+        } catch (e) {
+            op = [
+                6,
+                e
+            ];
+            y = 0;
+        } finally{
+            f = t = 0;
+        }
+        if (op[0] & 5) throw op[1];
+        return {
+            value: op[0] ? op[1] : void 0,
+            done: true
+        };
+    }
+}
+function executeQuery(query, options, transform) {
+    return _async_to_generator(function() {
+        var client, logger, pageSize, pageToken, includeBody, result, transformedResults, error;
+        return _ts_generator(this, function(_state) {
+            switch(_state.label){
+                case 0:
+                    client = options.client, logger = options.logger, pageSize = options.pageSize, pageToken = options.pageToken, includeBody = options.includeBody;
+                    // Validate pagination parameters
+                    if (pageSize !== undefined && (pageSize < 1 || pageSize > _constantsts.MAX_PAGE_SIZE)) {
+                        throw new Error("pageSize must be between 1 and ".concat(_constantsts.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');
+                    _state.label = 1;
+                case 1:
+                    _state.trys.push([
+                        1,
+                        3,
+                        ,
+                        4
+                    ]);
+                    return [
+                        4,
+                        (0, _searchexecution.searchMessages)(client, _object_spread_props(_object_spread({}, query !== undefined && {
+                            query: 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: logger
+                        }))
+                    ];
+                case 2:
+                    result = _state.sent();
+                    // Transform results
+                    transformedResults = result.messages.map(transform);
+                    logger.info("executeQuery: succeeded with ".concat(transformedResults.length, " results"));
+                    return [
+                        2,
+                        {
+                            success: true,
+                            items: transformedResults,
+                            metadata: {
+                                nextPageToken: result.nextPageToken
+                            }
+                        }
+                    ];
+                case 3:
+                    error = _state.sent();
+                    // Re-throw errors directly - no fallback logic
+                    logger.error('executeQuery: failed', {
+                        error: _instanceof(error, Error) ? error.message : String(error)
+                    });
+                    throw error;
+                case 4:
+                    return [
+                        2
+                    ];
+            }
+        });
+    })();
+}
+/* CJS INTEROP */ if (exports.__esModule && exports.default) { try { Object.defineProperty(exports.default, '__esModule', { value: true }); for (var key in exports) { exports.default[key] = exports[key]; } } catch (_) {}; module.exports = exports.default; }

package/dist/cjs/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":["executeQuery","query","options","transform","client","logger","pageSize","pageToken","includeBody","result","transformedResults","error","undefined","MAX_PAGE_SIZE","Error","trim","length","info","searchMessages","messages","map","success","items","metadata","nextPageToken","message","String"],"mappings":";;;;+BAoBsBA;;;eAAAA;;;2BAlBQ;+BAGC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAexB,SAAeA,aAAgBC,KAA4B,EAAEC,OAA4B,EAAEC,SAA+B;;YACvHC,QAAQC,QAAQC,UAAUC,WAAWC,aAerCC,QASAC,oBAWCC;;;;oBAnCDP,SAAqDF,QAArDE,QAAQC,SAA6CH,QAA7CG,QAAQC,WAAqCJ,QAArCI,UAAUC,YAA2BL,QAA3BK,WAAWC,cAAgBN,QAAhBM;oBAE7C,iCAAiC;oBACjC,IAAIF,aAAaM,aAAcN,CAAAA,WAAW,KAAKA,WAAWO,0BAAa,AAAD,GAAI;wBACxE,MAAM,IAAIC,MAAM,AAAC,kCAA+C,OAAdD,0BAAa;oBACjE;oBAEA,IAAIN,cAAcK,aAAa,OAAOL,cAAc,YAAYA,UAAUQ,IAAI,GAAGC,MAAM,KAAK,GAAG;wBAC7FX,OAAOY,IAAI,CAAC;oBACd;oBAEA,+CAA+C;oBAC/CZ,OAAOY,IAAI,CAAC;;;;;;;;;oBAGK;;wBAAMC,IAAAA,+BAAc,EAACd,QAAQ,wCACtCH,UAAUW,aAAa;4BAAEX,OAAAA;wBAAM;4BACnCK,QAAQ,EAAEA,qBAAAA,sBAAAA,WAAY;4BACtBC,WAAWA,aAAaA,UAAUQ,IAAI,GAAGC,MAAM,GAAG,IAAIT,YAAYK;4BAClEJ,WAAW,EAAEA,wBAAAA,yBAAAA,cAAe;4BAC5BH,QAAAA;;;;oBALII,SAAS;oBAQf,oBAAoB;oBACdC,qBAAqBD,OAAOU,QAAQ,CAACC,GAAG,CAACjB;oBAE/CE,OAAOY,IAAI,CAAC,AAAC,gCAAyD,OAA1BP,mBAAmBM,MAAM,EAAC;oBAEtE;;wBAAO;4BACLK,SAAS;4BACTC,OAAOZ;4BACPa,UAAU;gCACRC,eAAef,OAAOe,aAAa;4BACrC;wBACF;;;oBACOb;oBACP,+CAA+C;oBAC/CN,OAAOM,KAAK,CAAC,wBAAwB;wBAAEA,OAAOA,AAAK,YAALA,OAAiBG,SAAQH,MAAMc,OAAO,GAAGC,OAAOf;oBAAO;oBACrG,MAAMA;;;;;;;IAEV"}

package/dist/cjs/email/querying/pagination.d.cts

@@ -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/cjs/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[]>;