@mcp-z/mcp-gmail 1.0.0

package/dist/cjs/mcp/tools/messages-export-csv.js

@@ -0,0 +1,530 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", {
+    value: true
+});
+Object.defineProperty(exports, "default", {
+    enumerable: true,
+    get: function() {
+        return createTool;
+    }
+});
+var _email = require("@mcp-z/email");
+var _oauthgoogle = require("@mcp-z/oauth-google");
+var _server = require("@mcp-z/server");
+var _types = require("@modelcontextprotocol/sdk/types.js");
+var _sync = require("csv-stringify/sync");
+var _fs = require("fs");
+var _promises = require("fs/promises");
+var _googleapis = require("googleapis");
+var _zod = require("zod");
+var _constantsts = require("../../constants.js");
+var _htmlprocessing = require("../../email/parsing/html-processing.js");
+var _executequery = require("../../email/querying/execute-query.js");
+var _gmailqueryschema = require("../../schemas/gmail-query-schema.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
+        };
+    }
+}
+var AuthRequiredBranchSchema = _oauthgoogle.schemas.AuthRequiredBranchSchema;
+var DEFAULT_MAX_ITEMS = 10000;
+var MAX_EXPORT_ITEMS = 50000;
+var inputSchema = _zod.z.object({
+    query: _gmailqueryschema.GmailQuerySchema.optional().describe('Structured query object for filtering messages. Use query-syntax prompt for reference.'),
+    maxItems: _zod.z.number().int().positive().max(MAX_EXPORT_ITEMS).default(DEFAULT_MAX_ITEMS).describe("Maximum messages to export (default: ".concat(DEFAULT_MAX_ITEMS, ", max: ").concat(MAX_EXPORT_ITEMS, ")")),
+    filename: _zod.z.string().trim().min(1).default('gmail-messages.csv').describe('Output filename (default: gmail-messages.csv)'),
+    contentType: _email.EmailContentTypeSchema,
+    excludeThreadHistory: _email.ExcludeThreadHistorySchema
+});
+var successBranchSchema = _zod.z.object({
+    type: _zod.z.literal('success'),
+    uri: _zod.z.string().describe('File URI (file:// or http://)'),
+    filename: _zod.z.string().describe('Stored filename'),
+    rowCount: _zod.z.number().describe('Number of messages exported'),
+    truncated: _zod.z.boolean().describe('Whether export was truncated at maxItems')
+});
+var outputSchema = _zod.z.discriminatedUnion('type', [
+    successBranchSchema,
+    AuthRequiredBranchSchema
+]);
+var config = {
+    description: 'Export Gmail messages to CSV with streaming pagination. Returns file URI. Use query-syntax prompt for query reference.',
+    inputSchema: inputSchema,
+    outputSchema: _zod.z.object({
+        result: outputSchema
+    })
+};
+/**
+ * Handler for gmail-messages-export-csv tool
+ *
+ * CRITICAL: Streaming implementation per user requirements
+ * - Generate UUID upfront
+ * - Write CSV header immediately
+ * - Append rows as batches arrive
+ * - Delete partial file on error
+ * - NO RETRIES (fail fast on error)
+ */ function handler(_0, _1) {
+    return _async_to_generator(function(param, extra) {
+        var query, maxItems, filename, contentType, excludeThreadHistory, logger, storageContext, transport, storageDir, baseUrl, reservation, storedName, fullPath, gmail, csvHeaders, writeStream, headerLine, totalRows, nextPageToken, started, _exec_metadata, remainingItems, pageSize, exec, csvRows, rowsContent, durationMs, truncated, uri, result, error, _cleanupError, message;
+        return _ts_generator(this, function(_state) {
+            switch(_state.label){
+                case 0:
+                    query = param.query, maxItems = param.maxItems, filename = param.filename, contentType = param.contentType, excludeThreadHistory = param.excludeThreadHistory;
+                    logger = extra.logger;
+                    storageContext = extra.storageContext;
+                    transport = storageContext.transport, storageDir = storageContext.storageDir, baseUrl = storageContext.baseUrl;
+                    logger.info('gmail.messages.export-csv called', {
+                        query: query,
+                        maxItems: maxItems,
+                        filename: filename,
+                        accountId: extra.authContext.accountId
+                    });
+                    return [
+                        4,
+                        (0, _server.reserveFile)(filename, {
+                            storageDir: storageDir
+                        })
+                    ];
+                case 1:
+                    reservation = _state.sent();
+                    storedName = reservation.storedName, fullPath = reservation.fullPath;
+                    logger.info('gmail.messages.export-csv starting streaming export', {
+                        path: fullPath,
+                        maxItems: maxItems
+                    });
+                    _state.label = 2;
+                case 2:
+                    _state.trys.push([
+                        2,
+                        7,
+                        ,
+                        12
+                    ]);
+                    gmail = _googleapis.google.gmail({
+                        version: 'v1',
+                        auth: extra.authContext.auth
+                    });
+                    // Create CSV headers (all email fields)
+                    csvHeaders = [
+                        'id',
+                        'threadId',
+                        'from',
+                        'to',
+                        'cc',
+                        'bcc',
+                        'subject',
+                        'date',
+                        'snippet',
+                        'body',
+                        'provider',
+                        'labels'
+                    ];
+                    // Create write stream and write headers immediately
+                    writeStream = (0, _fs.createWriteStream)(fullPath, {
+                        encoding: 'utf-8'
+                    });
+                    headerLine = (0, _sync.stringify)([
+                        csvHeaders
+                    ], {
+                        header: false,
+                        quoted: true,
+                        quote: '"',
+                        escape: '"'
+                    });
+                    writeStream.write(headerLine);
+                    // Internal pagination loop - append to CSV with each batch
+                    // NO RETRIES: If any error occurs, fail the whole operation and clean up
+                    totalRows = 0;
+                    started = Date.now();
+                    _state.label = 3;
+                case 3:
+                    if (!(totalRows < maxItems)) return [
+                        3,
+                        5
+                    ];
+                    remainingItems = maxItems - totalRows;
+                    pageSize = Math.min(remainingItems, _constantsts.DEFAULT_PAGE_SIZE);
+                    return [
+                        4,
+                        (0, _executequery.executeQuery)(query, _object_spread_props(_object_spread({
+                            client: gmail,
+                            logger: logger,
+                            pageSize: pageSize
+                        }, nextPageToken !== undefined && {
+                            pageToken: nextPageToken
+                        }), {
+                            includeBody: true
+                        }), function(full) {
+                            var _ref;
+                            var _fullData_payload;
+                            // Type-safe property access with guards
+                            var fullData = full;
+                            var headersArray = Array.isArray(fullData === null || fullData === void 0 ? void 0 : (_fullData_payload = fullData.payload) === null || _fullData_payload === void 0 ? void 0 : _fullData_payload.headers) ? fullData.payload.headers : [];
+                            var headers = Object.fromEntries(headersArray.map(function(h) {
+                                var _header_name, _header_value;
+                                var header = h;
+                                return [
+                                    String((_header_name = header.name) !== null && _header_name !== void 0 ? _header_name : ''),
+                                    String((_header_value = header.value) !== null && _header_value !== void 0 ? _header_value : '')
+                                ];
+                            }));
+                            var payload = fullData === null || fullData === void 0 ? void 0 : fullData.payload;
+                            // Cast to Schema$MessagePart for extractBodyFromPayload
+                            var body = payload ? (0, _htmlprocessing.extractBodyFromPayload)(payload, {
+                                contentType: contentType,
+                                excludeThreadHistory: excludeThreadHistory
+                            }) : '';
+                            var labelIds = Array.isArray(fullData === null || fullData === void 0 ? void 0 : fullData.labelIds) ? fullData.labelIds.map(function(id) {
+                                return String(id !== null && id !== void 0 ? id : '');
+                            }) : [];
+                            return {
+                                id: String((_ref = fullData === null || fullData === void 0 ? void 0 : fullData.id) !== null && _ref !== void 0 ? _ref : ''),
+                                threadId: (fullData === null || fullData === void 0 ? void 0 : fullData.threadId) ? String(fullData.threadId) : '',
+                                from: (headers === null || headers === void 0 ? void 0 : headers.From) || '',
+                                to: (headers === null || headers === void 0 ? void 0 : headers.To) || '',
+                                cc: (headers === null || headers === void 0 ? void 0 : headers.Cc) || '',
+                                bcc: (headers === null || headers === void 0 ? void 0 : headers.Bcc) || '',
+                                subject: (headers === null || headers === void 0 ? void 0 : headers.Subject) || '',
+                                date: (headers === null || headers === void 0 ? void 0 : headers.Date) || '',
+                                snippet: (fullData === null || fullData === void 0 ? void 0 : fullData.snippet) ? String(fullData.snippet) : '',
+                                body: body,
+                                provider: 'gmail',
+                                labels: labelIds.join(';')
+                            };
+                        })
+                    ];
+                case 4:
+                    exec = _state.sent();
+                    // Type-safe CSV row mapping
+                    csvRows = exec.items.map(function(row) {
+                        return [
+                            row.id,
+                            row.threadId,
+                            row.from,
+                            row.to,
+                            row.cc,
+                            row.bcc,
+                            row.subject,
+                            row.date,
+                            row.snippet,
+                            row.body,
+                            row.provider,
+                            row.labels
+                        ];
+                    });
+                    // Append rows to CSV file immediately
+                    if (csvRows.length > 0) {
+                        rowsContent = (0, _sync.stringify)(csvRows, {
+                            header: false,
+                            quoted: true,
+                            quote: '"',
+                            escape: '"'
+                        });
+                        writeStream.write(rowsContent);
+                    }
+                    totalRows += exec.items.length;
+                    nextPageToken = (_exec_metadata = exec.metadata) === null || _exec_metadata === void 0 ? void 0 : _exec_metadata.nextPageToken;
+                    logger.info('gmail.messages.export-csv batch written', {
+                        batchSize: exec.items.length,
+                        totalRows: totalRows,
+                        hasMore: Boolean(nextPageToken)
+                    });
+                    // Exit if no more results or reached maxItems
+                    if (!nextPageToken || exec.items.length === 0) {
+                        return [
+                            3,
+                            5
+                        ];
+                    }
+                    return [
+                        3,
+                        3
+                    ];
+                case 5:
+                    // Close write stream
+                    return [
+                        4,
+                        new Promise(function(resolve, reject) {
+                            writeStream.end(function() {
+                                return resolve();
+                            });
+                            writeStream.on('error', reject);
+                        })
+                    ];
+                case 6:
+                    _state.sent();
+                    durationMs = Date.now() - started;
+                    truncated = totalRows >= maxItems && Boolean(nextPageToken);
+                    logger.info('gmail.messages.export-csv completed', {
+                        rowCount: totalRows,
+                        truncated: truncated,
+                        durationMs: durationMs,
+                        filename: storedName
+                    });
+                    // Generate URI based on transport type (stdio: file://, HTTP: http://)
+                    uri = (0, _server.getFileUri)(storedName, transport, _object_spread_props(_object_spread({
+                        storageDir: storageDir
+                    }, baseUrl && {
+                        baseUrl: baseUrl
+                    }), {
+                        endpoint: '/files'
+                    }));
+                    result = {
+                        type: 'success',
+                        uri: uri,
+                        filename: storedName,
+                        rowCount: totalRows,
+                        truncated: truncated
+                    };
+                    return [
+                        2,
+                        {
+                            content: [
+                                {
+                                    type: 'text',
+                                    text: JSON.stringify(result)
+                                }
+                            ],
+                            structuredContent: {
+                                result: result
+                            }
+                        }
+                    ];
+                case 7:
+                    error = _state.sent();
+                    _state.label = 8;
+                case 8:
+                    _state.trys.push([
+                        8,
+                        10,
+                        ,
+                        11
+                    ]);
+                    return [
+                        4,
+                        (0, _promises.unlink)(fullPath)
+                    ];
+                case 9:
+                    _state.sent();
+                    logger.debug('Cleaned up partial CSV file after error', {
+                        path: fullPath
+                    });
+                    return [
+                        3,
+                        11
+                    ];
+                case 10:
+                    _cleanupError = _state.sent();
+                    logger.debug('Could not clean up CSV file (may not exist)', {
+                        path: fullPath
+                    });
+                    return [
+                        3,
+                        11
+                    ];
+                case 11:
+                    message = _instanceof(error, Error) ? error.message : String(error);
+                    logger.error('gmail.messages.export-csv error', {
+                        error: message
+                    });
+                    throw new _types.McpError(_types.ErrorCode.InternalError, "Error exporting messages to CSV: ".concat(message), {
+                        stack: _instanceof(error, Error) ? error.stack : undefined
+                    });
+                case 12:
+                    return [
+                        2
+                    ];
+            }
+        });
+    }).apply(this, arguments);
+}
+function createTool() {
+    return {
+        name: 'messages-export-csv',
+        config: config,
+        handler: handler
+    };
+}
+/* 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/mcp/tools/messages-export-csv.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["/Users/kevin/Dev/Projects/ai/mcp-z/servers/mcp-gmail/src/mcp/tools/messages-export-csv.ts"],"sourcesContent":["import { EmailContentTypeSchema, ExcludeThreadHistorySchema } from '@mcp-z/email';\nimport type { EnrichedExtra } from '@mcp-z/oauth-google';\nimport { schemas } from '@mcp-z/oauth-google';\n\nconst { AuthRequiredBranchSchema } = schemas;\n\nimport { getFileUri, reserveFile, type ToolModule } from '@mcp-z/server';\nimport { ErrorCode, McpError } from '@modelcontextprotocol/sdk/types.js';\n\nimport { stringify } from 'csv-stringify/sync';\nimport { createWriteStream } from 'fs';\nimport { unlink } from 'fs/promises';\nimport { type gmail_v1, google } from 'googleapis';\nimport { z } from 'zod';\nimport { DEFAULT_PAGE_SIZE } from '../../constants.ts';\nimport { extractBodyFromPayload } from '../../email/parsing/html-processing.js';\nimport { executeQuery as executeGmailQuery } from '../../email/querying/execute-query.js';\nimport { GmailQuerySchema } from '../../schemas/gmail-query-schema.js';\nimport type { StorageExtra } from '../../types.js';\n\nconst DEFAULT_MAX_ITEMS = 10000;\nconst MAX_EXPORT_ITEMS = 50000;\n\n/**\n * CSV row format based on EmailDetail\n * All fields are strings (empty string instead of undefined)\n * Includes additional CSV-specific fields: provider and labels\n */\ninterface CsvRow {\n  id: string;\n  threadId: string;\n  from: string;\n  to: string;\n  cc: string;\n  bcc: string;\n  subject: string;\n  date: string;\n  snippet: string;\n  body: string;\n  provider: string;\n  labels: string;\n}\n\nconst inputSchema = z.object({\n  query: GmailQuerySchema.optional().describe('Structured query object for filtering messages. Use query-syntax prompt for reference.'),\n  maxItems: z.number().int().positive().max(MAX_EXPORT_ITEMS).default(DEFAULT_MAX_ITEMS).describe(`Maximum messages to export (default: ${DEFAULT_MAX_ITEMS}, max: ${MAX_EXPORT_ITEMS})`),\n  filename: z.string().trim().min(1).default('gmail-messages.csv').describe('Output filename (default: gmail-messages.csv)'),\n  contentType: EmailContentTypeSchema,\n  excludeThreadHistory: ExcludeThreadHistorySchema,\n});\n\nconst successBranchSchema = z.object({\n  type: z.literal('success'),\n  uri: z.string().describe('File URI (file:// or http://)'),\n  filename: z.string().describe('Stored filename'),\n  rowCount: z.number().describe('Number of messages exported'),\n  truncated: z.boolean().describe('Whether export was truncated at maxItems'),\n});\n\nconst outputSchema = z.discriminatedUnion('type', [successBranchSchema, AuthRequiredBranchSchema]);\n\nconst config = {\n  description: 'Export Gmail messages to CSV with streaming pagination. Returns file URI. Use query-syntax prompt for query reference.',\n  inputSchema: inputSchema,\n  outputSchema: z.object({\n    result: outputSchema,\n  }),\n} as const;\n\nexport type Input = z.infer<typeof inputSchema>;\nexport type Output = z.infer<typeof outputSchema>;\n\n/**\n * Handler for gmail-messages-export-csv tool\n *\n * CRITICAL: Streaming implementation per user requirements\n * - Generate UUID upfront\n * - Write CSV header immediately\n * - Append rows as batches arrive\n * - Delete partial file on error\n * - NO RETRIES (fail fast on error)\n */\nasync function handler({ query, maxItems, filename, contentType, excludeThreadHistory }: Input, extra: EnrichedExtra & StorageExtra) {\n  const logger = extra.logger;\n  const { storageContext } = extra;\n  const { transport, storageDir, baseUrl } = storageContext;\n\n  logger.info('gmail.messages.export-csv called', {\n    query,\n    maxItems,\n    filename,\n    accountId: extra.authContext.accountId,\n  });\n\n  // Reserve file location for streaming write (creates directory, generates ID, formats filename)\n  const reservation = await reserveFile(filename, {\n    storageDir,\n  });\n  const { storedName, fullPath } = reservation;\n\n  logger.info('gmail.messages.export-csv starting streaming export', { path: fullPath, maxItems });\n\n  try {\n    const gmail = google.gmail({ version: 'v1', auth: extra.authContext.auth });\n\n    // Create CSV headers (all email fields)\n    const csvHeaders = ['id', 'threadId', 'from', 'to', 'cc', 'bcc', 'subject', 'date', 'snippet', 'body', 'provider', 'labels'];\n\n    // Create write stream and write headers immediately\n    const writeStream = createWriteStream(fullPath, { encoding: 'utf-8' });\n    const headerLine = stringify([csvHeaders], { header: false, quoted: true, quote: '\"', escape: '\"' });\n    writeStream.write(headerLine);\n\n    // Internal pagination loop - append to CSV with each batch\n    // NO RETRIES: If any error occurs, fail the whole operation and clean up\n    let totalRows = 0;\n    let nextPageToken: string | undefined;\n    const started = Date.now();\n\n    while (totalRows < maxItems) {\n      const remainingItems = maxItems - totalRows;\n      const pageSize = Math.min(remainingItems, DEFAULT_PAGE_SIZE);\n\n      const exec: {\n        items: CsvRow[];\n        metadata?: { nextPageToken?: string };\n      } = await executeGmailQuery(\n        query,\n        {\n          client: gmail,\n          logger,\n          pageSize,\n          ...(nextPageToken !== undefined && { pageToken: nextPageToken }),\n          includeBody: true, // Always include body for CSV export\n        },\n        (full: unknown): CsvRow => {\n          // Type-safe property access with guards\n          const fullData = full as {\n            id?: unknown;\n            threadId?: unknown;\n            snippet?: unknown;\n            labelIds?: unknown[];\n            payload?: { headers?: unknown[] };\n          };\n\n          const headersArray = Array.isArray(fullData?.payload?.headers) ? fullData.payload.headers : [];\n          const headers = Object.fromEntries(\n            headersArray.map((h: unknown) => {\n              const header = h as { name?: unknown; value?: unknown };\n              return [String(header.name ?? ''), String(header.value ?? '')];\n            })\n          );\n\n          const payload = fullData?.payload;\n          // Cast to Schema$MessagePart for extractBodyFromPayload\n          const body = payload ? extractBodyFromPayload(payload as gmail_v1.Schema$MessagePart, { contentType, excludeThreadHistory }) : '';\n\n          const labelIds = Array.isArray(fullData?.labelIds) ? fullData.labelIds.map((id) => String(id ?? '')) : [];\n\n          return {\n            id: String(fullData?.id ?? ''),\n            threadId: fullData?.threadId ? String(fullData.threadId) : '',\n            from: headers?.From || '',\n            to: headers?.To || '',\n            cc: headers?.Cc || '',\n            bcc: headers?.Bcc || '',\n            subject: headers?.Subject || '',\n            date: headers?.Date || '',\n            snippet: fullData?.snippet ? String(fullData.snippet) : '',\n            body,\n            provider: 'gmail',\n            labels: labelIds.join(';'),\n          };\n        }\n      );\n\n      // Type-safe CSV row mapping\n      const csvRows = exec.items.map((row) => {\n        return [row.id, row.threadId, row.from, row.to, row.cc, row.bcc, row.subject, row.date, row.snippet, row.body, row.provider, row.labels];\n      });\n\n      // Append rows to CSV file immediately\n      if (csvRows.length > 0) {\n        const rowsContent = stringify(csvRows, { header: false, quoted: true, quote: '\"', escape: '\"' });\n        writeStream.write(rowsContent);\n      }\n\n      totalRows += exec.items.length;\n      nextPageToken = exec.metadata?.nextPageToken;\n\n      logger.info('gmail.messages.export-csv batch written', {\n        batchSize: exec.items.length,\n        totalRows,\n        hasMore: Boolean(nextPageToken),\n      });\n\n      // Exit if no more results or reached maxItems\n      if (!nextPageToken || exec.items.length === 0) {\n        break;\n      }\n    }\n\n    // Close write stream\n    await new Promise<void>((resolve, reject) => {\n      writeStream.end(() => resolve());\n      writeStream.on('error', reject);\n    });\n\n    const durationMs = Date.now() - started;\n    const truncated = totalRows >= maxItems && Boolean(nextPageToken);\n\n    logger.info('gmail.messages.export-csv completed', {\n      rowCount: totalRows,\n      truncated,\n      durationMs,\n      filename: storedName,\n    });\n\n    // Generate URI based on transport type (stdio: file://, HTTP: http://)\n    const uri = getFileUri(storedName, transport, {\n      storageDir,\n      ...(baseUrl && { baseUrl }),\n      endpoint: '/files',\n    });\n\n    const result: Output = {\n      type: 'success' as const,\n      uri,\n      filename: storedName,\n      rowCount: totalRows,\n      truncated,\n    };\n\n    return {\n      content: [\n        {\n          type: 'text' as const,\n          text: JSON.stringify(result),\n        },\n      ],\n      structuredContent: { result },\n    };\n  } catch (error) {\n    // CRITICAL: Clean up partial CSV file on error\n    try {\n      await unlink(fullPath);\n      logger.debug('Cleaned up partial CSV file after error', { path: fullPath });\n    } catch (_cleanupError) {\n      logger.debug('Could not clean up CSV file (may not exist)', { path: fullPath });\n    }\n\n    const message = error instanceof Error ? error.message : String(error);\n    logger.error('gmail.messages.export-csv error', { error: message });\n\n    throw new McpError(ErrorCode.InternalError, `Error exporting messages to CSV: ${message}`, {\n      stack: error instanceof Error ? error.stack : undefined,\n    });\n  }\n}\n\nexport default function createTool() {\n  return {\n    name: 'messages-export-csv',\n    config,\n    handler,\n  } satisfies ToolModule;\n}\n"],"names":["createTool","AuthRequiredBranchSchema","schemas","DEFAULT_MAX_ITEMS","MAX_EXPORT_ITEMS","inputSchema","z","object","query","GmailQuerySchema","optional","describe","maxItems","number","int","positive","max","default","filename","string","trim","min","contentType","EmailContentTypeSchema","excludeThreadHistory","ExcludeThreadHistorySchema","successBranchSchema","type","literal","uri","rowCount","truncated","boolean","outputSchema","discriminatedUnion","config","description","result","handler","extra","logger","storageContext","transport","storageDir","baseUrl","reservation","storedName","fullPath","gmail","csvHeaders","writeStream","headerLine","totalRows","nextPageToken","started","exec","remainingItems","pageSize","csvRows","rowsContent","durationMs","error","_cleanupError","message","info","accountId","authContext","reserveFile","path","google","version","auth","createWriteStream","encoding","stringify","header","quoted","quote","escape","write","Date","now","Math","DEFAULT_PAGE_SIZE","executeGmailQuery","client","undefined","pageToken","includeBody","full","fullData","headersArray","Array","isArray","payload","headers","Object","fromEntries","map","h","String","name","value","body","extractBodyFromPayload","labelIds","id","threadId","from","From","to","To","cc","Cc","bcc","Bcc","subject","Subject","date","snippet","provider","labels","join","items","row","length","metadata","batchSize","hasMore","Boolean","Promise","resolve","reject","end","on","getFileUri","endpoint","content","text","JSON","structuredContent","unlink","debug","Error","McpError","ErrorCode","InternalError","stack"],"mappings":";;;;+BAoQA;;;eAAwBA;;;qBApQ2C;2BAE3C;sBAIiC;qBACrB;oBAEV;kBACQ;wBACX;0BACe;mBACpB;2BACgB;8BACK;4BACW;gCACjB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAbjC,IAAM,AAAEC,2BAA6BC,oBAAO,CAApCD;AAgBR,IAAME,oBAAoB;AAC1B,IAAMC,mBAAmB;AAsBzB,IAAMC,cAAcC,MAAC,CAACC,MAAM,CAAC;IAC3BC,OAAOC,kCAAgB,CAACC,QAAQ,GAAGC,QAAQ,CAAC;IAC5CC,UAAUN,MAAC,CAACO,MAAM,GAAGC,GAAG,GAAGC,QAAQ,GAAGC,GAAG,CAACZ,kBAAkBa,OAAO,CAACd,mBAAmBQ,QAAQ,CAAC,AAAC,wCAAkEP,OAA3BD,mBAAkB,WAA0B,OAAjBC,kBAAiB;IACpLc,UAAUZ,MAAC,CAACa,MAAM,GAAGC,IAAI,GAAGC,GAAG,CAAC,GAAGJ,OAAO,CAAC,sBAAsBN,QAAQ,CAAC;IAC1EW,aAAaC,6BAAsB;IACnCC,sBAAsBC,iCAA0B;AAClD;AAEA,IAAMC,sBAAsBpB,MAAC,CAACC,MAAM,CAAC;IACnCoB,MAAMrB,MAAC,CAACsB,OAAO,CAAC;IAChBC,KAAKvB,MAAC,CAACa,MAAM,GAAGR,QAAQ,CAAC;IACzBO,UAAUZ,MAAC,CAACa,MAAM,GAAGR,QAAQ,CAAC;IAC9BmB,UAAUxB,MAAC,CAACO,MAAM,GAAGF,QAAQ,CAAC;IAC9BoB,WAAWzB,MAAC,CAAC0B,OAAO,GAAGrB,QAAQ,CAAC;AAClC;AAEA,IAAMsB,eAAe3B,MAAC,CAAC4B,kBAAkB,CAAC,QAAQ;IAACR;IAAqBzB;CAAyB;AAEjG,IAAMkC,SAAS;IACbC,aAAa;IACb/B,aAAaA;IACb4B,cAAc3B,MAAC,CAACC,MAAM,CAAC;QACrB8B,QAAQJ;IACV;AACF;AAKA;;;;;;;;;CASC,GACD,SAAeK;wCAAQ,KAAuE,EAAEC,KAAmC;YAA1G/B,OAAOI,UAAUM,UAAUI,aAAaE,sBACzDgB,QACEC,gBACAC,WAAWC,YAAYC,SAUzBC,aAGEC,YAAYC,UAKZC,OAGAC,YAGAC,aACAC,YAKFC,WACAC,eACEC,SAuEYC,gBApEVC,gBACAC,UAEAF,MAsDAG,SAMEC,aAyBJC,YACA7B,WAUAF,KAMAQ,QAiBCwB,OAKEC,eAIHC;;;;oBAzKevD,QAAF,MAAEA,OAAOI,WAAT,MAASA,UAAUM,WAAnB,MAAmBA,UAAUI,cAA7B,MAA6BA,aAAaE,uBAA1C,MAA0CA;oBACzDgB,SAASD,MAAMC,MAAM;oBACnBC,iBAAmBF,MAAnBE;oBACAC,YAAmCD,eAAnCC,WAAWC,aAAwBF,eAAxBE,YAAYC,UAAYH,eAAZG;oBAE/BJ,OAAOwB,IAAI,CAAC,oCAAoC;wBAC9CxD,OAAAA;wBACAI,UAAAA;wBACAM,UAAAA;wBACA+C,WAAW1B,MAAM2B,WAAW,CAACD,SAAS;oBACxC;oBAGoB;;wBAAME,IAAAA,mBAAW,EAACjD,UAAU;4BAC9CyB,YAAAA;wBACF;;;oBAFME,cAAc;oBAGZC,aAAyBD,YAAzBC,YAAYC,WAAaF,YAAbE;oBAEpBP,OAAOwB,IAAI,CAAC,uDAAuD;wBAAEI,MAAMrB;wBAAUnC,UAAAA;oBAAS;;;;;;;;;oBAGtFoC,QAAQqB,kBAAM,CAACrB,KAAK,CAAC;wBAAEsB,SAAS;wBAAMC,MAAMhC,MAAM2B,WAAW,CAACK,IAAI;oBAAC;oBAEzE,wCAAwC;oBAClCtB;wBAAc;wBAAM;wBAAY;wBAAQ;wBAAM;wBAAM;wBAAO;wBAAW;wBAAQ;wBAAW;wBAAQ;wBAAY;;oBAEnH,oDAAoD;oBAC9CC,cAAcsB,IAAAA,qBAAiB,EAACzB,UAAU;wBAAE0B,UAAU;oBAAQ;oBAC9DtB,aAAauB,IAAAA,eAAS;wBAAEzB;uBAAa;wBAAE0B,QAAQ;wBAAOC,QAAQ;wBAAMC,OAAO;wBAAKC,QAAQ;oBAAI;oBAClG5B,YAAY6B,KAAK,CAAC5B;oBAElB,2DAA2D;oBAC3D,yEAAyE;oBACrEC,YAAY;oBAEVE,UAAU0B,KAAKC,GAAG;;;yBAEjB7B,CAAAA,YAAYxC,QAAO;;;;oBAClB4C,iBAAiB5C,WAAWwC;oBAC5BK,WAAWyB,KAAK7D,GAAG,CAACmC,gBAAgB2B,8BAAiB;oBAKvD;;wBAAMC,IAAAA,0BAAiB,EACzB5E,OACA;4BACE6E,QAAQrC;4BACRR,QAAAA;4BACAiB,UAAAA;2BACIJ,kBAAkBiC,aAAa;4BAAEC,WAAWlC;wBAAc;4BAC9DmC,aAAa;4BAEf,SAACC;;gCAUoCC;4BATnC,wCAAwC;4BACxC,IAAMA,WAAWD;4BAQjB,IAAME,eAAeC,MAAMC,OAAO,CAACH,qBAAAA,gCAAAA,oBAAAA,SAAUI,OAAO,cAAjBJ,wCAAAA,kBAAmBK,OAAO,IAAIL,SAASI,OAAO,CAACC,OAAO,GAAG,EAAE;4BAC9F,IAAMA,UAAUC,OAAOC,WAAW,CAChCN,aAAaO,GAAG,CAAC,SAACC;oCAEDxB,cAA2BA;gCAD1C,IAAMA,SAASwB;gCACf,OAAO;oCAACC,QAAOzB,eAAAA,OAAO0B,IAAI,cAAX1B,0BAAAA,eAAe;oCAAKyB,QAAOzB,gBAAAA,OAAO2B,KAAK,cAAZ3B,2BAAAA,gBAAgB;iCAAI;4BAChE;4BAGF,IAAMmB,UAAUJ,qBAAAA,+BAAAA,SAAUI,OAAO;4BACjC,wDAAwD;4BACxD,IAAMS,OAAOT,UAAUU,IAAAA,sCAAsB,EAACV,SAAwC;gCAAExE,aAAAA;gCAAaE,sBAAAA;4BAAqB,KAAK;4BAE/H,IAAMiF,WAAWb,MAAMC,OAAO,CAACH,qBAAAA,+BAAAA,SAAUe,QAAQ,IAAIf,SAASe,QAAQ,CAACP,GAAG,CAAC,SAACQ;uCAAON,OAAOM,eAAAA,gBAAAA,KAAM;iCAAO,EAAE;4BAEzG,OAAO;gCACLA,IAAIN,eAAOV,qBAAAA,+BAAAA,SAAUgB,EAAE,uCAAI;gCAC3BC,UAAUjB,CAAAA,qBAAAA,+BAAAA,SAAUiB,QAAQ,IAAGP,OAAOV,SAASiB,QAAQ,IAAI;gCAC3DC,MAAMb,CAAAA,oBAAAA,8BAAAA,QAASc,IAAI,KAAI;gCACvBC,IAAIf,CAAAA,oBAAAA,8BAAAA,QAASgB,EAAE,KAAI;gCACnBC,IAAIjB,CAAAA,oBAAAA,8BAAAA,QAASkB,EAAE,KAAI;gCACnBC,KAAKnB,CAAAA,oBAAAA,8BAAAA,QAASoB,GAAG,KAAI;gCACrBC,SAASrB,CAAAA,oBAAAA,8BAAAA,QAASsB,OAAO,KAAI;gCAC7BC,MAAMvB,CAAAA,oBAAAA,8BAAAA,QAASf,IAAI,KAAI;gCACvBuC,SAAS7B,CAAAA,qBAAAA,+BAAAA,SAAU6B,OAAO,IAAGnB,OAAOV,SAAS6B,OAAO,IAAI;gCACxDhB,MAAAA;gCACAiB,UAAU;gCACVC,QAAQhB,SAASiB,IAAI,CAAC;4BACxB;wBACF;;;oBAlDInE,OAGF;oBAkDJ,4BAA4B;oBACtBG,UAAUH,KAAKoE,KAAK,CAACzB,GAAG,CAAC,SAAC0B;wBAC9B,OAAO;4BAACA,IAAIlB,EAAE;4BAAEkB,IAAIjB,QAAQ;4BAAEiB,IAAIhB,IAAI;4BAAEgB,IAAId,EAAE;4BAAEc,IAAIZ,EAAE;4BAAEY,IAAIV,GAAG;4BAAEU,IAAIR,OAAO;4BAAEQ,IAAIN,IAAI;4BAAEM,IAAIL,OAAO;4BAAEK,IAAIrB,IAAI;4BAAEqB,IAAIJ,QAAQ;4BAAEI,IAAIH,MAAM;yBAAC;oBAC1I;oBAEA,sCAAsC;oBACtC,IAAI/D,QAAQmE,MAAM,GAAG,GAAG;wBAChBlE,cAAce,IAAAA,eAAS,EAAChB,SAAS;4BAAEiB,QAAQ;4BAAOC,QAAQ;4BAAMC,OAAO;4BAAKC,QAAQ;wBAAI;wBAC9F5B,YAAY6B,KAAK,CAACpB;oBACpB;oBAEAP,aAAaG,KAAKoE,KAAK,CAACE,MAAM;oBAC9BxE,iBAAgBE,iBAAAA,KAAKuE,QAAQ,cAAbvE,qCAAAA,eAAeF,aAAa;oBAE5Cb,OAAOwB,IAAI,CAAC,2CAA2C;wBACrD+D,WAAWxE,KAAKoE,KAAK,CAACE,MAAM;wBAC5BzE,WAAAA;wBACA4E,SAASC,QAAQ5E;oBACnB;oBAEA,8CAA8C;oBAC9C,IAAI,CAACA,iBAAiBE,KAAKoE,KAAK,CAACE,MAAM,KAAK,GAAG;wBAC7C;;;;oBACF;;;;;;oBAGF,qBAAqB;oBACrB;;wBAAM,IAAIK,QAAc,SAACC,SAASC;4BAChClF,YAAYmF,GAAG,CAAC;uCAAMF;;4BACtBjF,YAAYoF,EAAE,CAAC,SAASF;wBAC1B;;;oBAHA;oBAKMxE,aAAaoB,KAAKC,GAAG,KAAK3B;oBAC1BvB,YAAYqB,aAAaxC,YAAYqH,QAAQ5E;oBAEnDb,OAAOwB,IAAI,CAAC,uCAAuC;wBACjDlC,UAAUsB;wBACVrB,WAAAA;wBACA6B,YAAAA;wBACA1C,UAAU4B;oBACZ;oBAEA,uEAAuE;oBACjEjB,MAAM0G,IAAAA,kBAAU,EAACzF,YAAYJ,WAAW;wBAC5CC,YAAAA;uBACIC,WAAW;wBAAEA,SAAAA;oBAAQ;wBACzB4F,UAAU;;oBAGNnG,SAAiB;wBACrBV,MAAM;wBACNE,KAAAA;wBACAX,UAAU4B;wBACVhB,UAAUsB;wBACVrB,WAAAA;oBACF;oBAEA;;wBAAO;4BACL0G,OAAO;gCACL;oCACE9G,MAAM;oCACN+G,MAAMC,KAAKjE,SAAS,CAACrC;gCACvB;;4BAEFuG,mBAAmB;gCAAEvG,QAAAA;4BAAO;wBAC9B;;;oBACOwB;;;;;;;;;oBAGL;;wBAAMgF,IAAAA,gBAAM,EAAC9F;;;oBAAb;oBACAP,OAAOsG,KAAK,CAAC,2CAA2C;wBAAE1E,MAAMrB;oBAAS;;;;;;oBAClEe;oBACPtB,OAAOsG,KAAK,CAAC,+CAA+C;wBAAE1E,MAAMrB;oBAAS;;;;;;oBAGzEgB,UAAUF,AAAK,YAALA,OAAiBkF,SAAQlF,MAAME,OAAO,GAAGqC,OAAOvC;oBAChErB,OAAOqB,KAAK,CAAC,mCAAmC;wBAAEA,OAAOE;oBAAQ;oBAEjE,MAAM,IAAIiF,eAAQ,CAACC,gBAAS,CAACC,aAAa,EAAE,AAAC,oCAA2C,OAARnF,UAAW;wBACzFoF,OAAOtF,AAAK,YAALA,OAAiBkF,SAAQlF,MAAMsF,KAAK,GAAG7D;oBAChD;;;;;;;IAEJ;;AAEe,SAAStF;IACtB,OAAO;QACLqG,MAAM;QACNlE,QAAAA;QACAG,SAAAA;IACF;AACF"}

package/dist/cjs/package.json

@@ -0,0 +1 @@
+{ "type": "commonjs" }

package/dist/cjs/schemas/gmail-query-schema.d.cts

@@ -0,0 +1,36 @@
+import { type BaseEmailQueryFields, type FieldOperator } from '@mcp-z/email';
+import { z } from 'zod';
+/**
+ * Gmail-specific query schema with recursive operators and Gmail features.
+ *
+ * Includes Gmail-specific features:
+ * - fuzzyPhrase: Approximate phrase matching (Gmail's quoted string behavior with relevance ranking)
+ * - categories: Gmail system categories (primary, social, promotions, updates, forums)
+ * - label: User-created Gmail labels (case-sensitive, discovered via gmail-labels-list)
+ * - rawGmailQuery: Escape hatch for advanced Gmail query syntax
+ *
+ * Plus all base fields from baseEmailQueryFields:
+ * - Email addresses: from, to, cc, bcc (support string or field operators)
+ * - Content: subject, body, text
+ * - Flags: hasAttachment, isRead
+ * - Date range: date { $gte, $lt }
+ * - Logical operators: $and, $or, $not (recursive)
+ *
+ * Note: Cast through unknown to work around Zod's lazy schema type inference issue
+ * with exactOptionalPropertyTypes. The runtime schema is correct; this cast ensures
+ * TypeScript sees the strict GmailQuery type everywhere the schema is used.
+ */
+export declare const GmailQuerySchema: z.ZodType<GmailQuery>;
+export type GmailQuery = BaseEmailQueryFields & {
+    $and?: GmailQuery[];
+    $or?: GmailQuery[];
+    $not?: GmailQuery;
+    fuzzyPhrase?: string;
+    categories?: 'primary' | 'social' | 'promotions' | 'updates' | 'forums' | {
+        $any?: ('primary' | 'social' | 'promotions' | 'updates' | 'forums')[];
+        $all?: ('primary' | 'social' | 'promotions' | 'updates' | 'forums')[];
+        $none?: ('primary' | 'social' | 'promotions' | 'updates' | 'forums')[];
+    };
+    label?: string | FieldOperator;
+    rawGmailQuery?: string;
+};

package/dist/cjs/schemas/gmail-query-schema.d.ts

@@ -0,0 +1,36 @@
+import { type BaseEmailQueryFields, type FieldOperator } from '@mcp-z/email';
+import { z } from 'zod';
+/**
+ * Gmail-specific query schema with recursive operators and Gmail features.
+ *
+ * Includes Gmail-specific features:
+ * - fuzzyPhrase: Approximate phrase matching (Gmail's quoted string behavior with relevance ranking)
+ * - categories: Gmail system categories (primary, social, promotions, updates, forums)
+ * - label: User-created Gmail labels (case-sensitive, discovered via gmail-labels-list)
+ * - rawGmailQuery: Escape hatch for advanced Gmail query syntax
+ *
+ * Plus all base fields from baseEmailQueryFields:
+ * - Email addresses: from, to, cc, bcc (support string or field operators)
+ * - Content: subject, body, text
+ * - Flags: hasAttachment, isRead
+ * - Date range: date { $gte, $lt }
+ * - Logical operators: $and, $or, $not (recursive)
+ *
+ * Note: Cast through unknown to work around Zod's lazy schema type inference issue
+ * with exactOptionalPropertyTypes. The runtime schema is correct; this cast ensures
+ * TypeScript sees the strict GmailQuery type everywhere the schema is used.
+ */
+export declare const GmailQuerySchema: z.ZodType<GmailQuery>;
+export type GmailQuery = BaseEmailQueryFields & {
+    $and?: GmailQuery[];
+    $or?: GmailQuery[];
+    $not?: GmailQuery;
+    fuzzyPhrase?: string;
+    categories?: 'primary' | 'social' | 'promotions' | 'updates' | 'forums' | {
+        $any?: ('primary' | 'social' | 'promotions' | 'updates' | 'forums')[];
+        $all?: ('primary' | 'social' | 'promotions' | 'updates' | 'forums')[];
+        $none?: ('primary' | 'social' | 'promotions' | 'updates' | 'forums')[];
+    };
+    label?: string | FieldOperator;
+    rawGmailQuery?: string;
+};