@triffon/google-docs-mcp 1.11.3-triffon

package/dist/tools/docs/readGoogleDoc.js

@@ -0,0 +1,164 @@
+import { UserError } from 'fastmcp';
+import { z } from 'zod';
+import { getDocsClient, getDriveClient } from '../../clients.js';
+import { DocumentIdParameter, NotImplementedError } from '../../types.js';
+import * as GDocsHelpers from '../../googleDocsApiHelpers.js';
+import { docsJsonToMarkdown } from '../../markdown-transformer/index.js';
+import { buildTabsFieldMask } from './tabFieldMasks.js';
+export function register(server) {
+    server.addTool({
+        name: 'readDocument',
+        description: "Reads the content of a Google Document. Returns plain text by default. Use format='markdown' to get formatted content suitable for editing and re-uploading with replaceDocumentWithMarkdown, or format='json' for the raw document structure.",
+        parameters: DocumentIdParameter.extend({
+            format: z
+                .enum(['text', 'json', 'markdown'])
+                .optional()
+                .default('text')
+                .describe("Output format: 'text' (plain text), 'json' (raw API structure, complex), 'markdown' (experimental conversion)."),
+            maxLength: z
+                .number()
+                .optional()
+                .describe('Maximum character limit for text output. If not specified, returns full document content. Use this to limit very large documents.'),
+            tabId: z
+                .string()
+                .optional()
+                .describe('The ID of the specific tab to read. If not specified, reads the first tab (or legacy document.body for documents without tabs).'),
+        }),
+        execute: async (args, { log }) => {
+            const docs = await getDocsClient();
+            log.info(`Reading Google Doc: ${args.documentId}, Format: ${args.format}${args.tabId ? `, Tab: ${args.tabId}` : ''}`);
+            try {
+                // Determine if we need tabs content
+                const needsTabsContent = !!args.tabId;
+                const fields = args.format === 'json' || args.format === 'markdown'
+                    ? '*' // Get everything for structure analysis
+                    : 'body(content(paragraph(elements(textRun(content)))))'; // Just text content
+                const res = await docs.documents.get({
+                    documentId: args.documentId,
+                    includeTabsContent: needsTabsContent,
+                    suggestionsViewMode: 'PREVIEW_WITHOUT_SUGGESTIONS',
+                    fields: needsTabsContent
+                        ? `title,documentId,${buildTabsFieldMask('documentTab(body,documentStyle,namedStyles,lists)')}`
+                        : fields,
+                });
+                log.info(`Fetched doc: ${args.documentId}${args.tabId ? ` (tab: ${args.tabId})` : ''}`);
+                // If tabId is specified, find the specific tab
+                let contentSource;
+                if (args.tabId) {
+                    const targetTab = GDocsHelpers.findTabById(res.data, args.tabId);
+                    if (!targetTab) {
+                        throw new UserError(`Tab with ID "${args.tabId}" not found in document.`);
+                    }
+                    if (!targetTab.documentTab) {
+                        throw new UserError(`Tab "${args.tabId}" does not have content (may not be a document tab).`);
+                    }
+                    contentSource = { body: targetTab.documentTab.body };
+                    log.info(`Using content from tab: ${targetTab.tabProperties?.title || 'Untitled'}`);
+                }
+                else {
+                    // Use the document body (backward compatible)
+                    contentSource = res.data;
+                }
+                if (args.format === 'json') {
+                    const jsonContent = JSON.stringify(contentSource, null, 2);
+                    // Apply length limit to JSON if specified
+                    if (args.maxLength && jsonContent.length > args.maxLength) {
+                        return (jsonContent.substring(0, args.maxLength) +
+                            `\n... [JSON truncated: ${jsonContent.length} total chars]`);
+                    }
+                    return jsonContent;
+                }
+                if (args.format === 'markdown') {
+                    const markdownContent = docsJsonToMarkdown(contentSource);
+                    const totalLength = markdownContent.length;
+                    log.info(`Generated markdown: ${totalLength} characters`);
+                    // Apply length limit to markdown if specified
+                    if (args.maxLength && totalLength > args.maxLength) {
+                        const truncatedContent = markdownContent.substring(0, args.maxLength);
+                        return `${truncatedContent}\n\n... [Markdown truncated to ${args.maxLength} chars of ${totalLength} total. Use maxLength parameter to adjust limit or remove it to get full content.]`;
+                    }
+                    return markdownContent;
+                }
+                // Default: Text format - extract all text content
+                let textContent = '';
+                let elementCount = 0;
+                const extractFromElements = (elements) => {
+                    for (const element of elements || []) {
+                        elementCount++;
+                        if (element.paragraph?.elements) {
+                            for (const pe of element.paragraph.elements) {
+                                if (pe.textRun?.content)
+                                    textContent += pe.textRun.content;
+                            }
+                        }
+                        if (element.table?.tableRows) {
+                            for (const row of element.table.tableRows) {
+                                for (const cell of row.tableCells || []) {
+                                    extractFromElements(cell.content || []);
+                                }
+                            }
+                        }
+                    }
+                };
+                // Process all content elements from contentSource
+                contentSource.body?.content?.forEach((element) => {
+                    extractFromElements([element]);
+                });
+                if (!textContent.trim())
+                    return 'Document found, but appears empty.';
+                const totalLength = textContent.length;
+                log.info(`Document contains ${totalLength} characters across ${elementCount} elements`);
+                log.info(`maxLength parameter: ${args.maxLength || 'not specified'}`);
+                // Apply length limit only if specified
+                if (args.maxLength && totalLength > args.maxLength) {
+                    const truncatedContent = textContent.substring(0, args.maxLength);
+                    log.info(`Truncating content from ${totalLength} to ${args.maxLength} characters`);
+                    return `Content (truncated to ${args.maxLength} chars of ${totalLength} total):\n---\n${truncatedContent}\n\n... [Document continues for ${totalLength - args.maxLength} more characters. Use maxLength parameter to adjust limit or remove it to get full content.]`;
+                }
+                // Return full content
+                const fullResponse = `Content (${totalLength} characters):\n---\n${textContent}`;
+                const responseLength = fullResponse.length;
+                log.info(`Returning full content: ${responseLength} characters in response (${totalLength} content + ${responseLength - totalLength} metadata)`);
+                return fullResponse;
+            }
+            catch (error) {
+                log.error(`Error reading doc ${args.documentId}: ${error.message || 'Unknown error'} (code: ${error.code || 'N/A'})`);
+                // Handle errors thrown by helpers or API directly
+                if (error instanceof UserError)
+                    throw error;
+                if (error instanceof NotImplementedError)
+                    throw error;
+                // Generic fallback for API errors not caught by helpers
+                if (error.code === 404)
+                    throw new UserError(`Doc not found (ID: ${args.documentId}).`);
+                if (error.code === 403) {
+                    // The Docs API may be blocked by Workspace admin policy even when the Drive API is
+                    // accessible. Fall back to drive.files.export() for plain-text format, which uses
+                    // the Drive API and respects supportsAllDrives for Shared Drive documents.
+                    if (!args.format || args.format === 'text') {
+                        try {
+                            log.info(`Docs API returned 403, falling back to Drive export for ${args.documentId}`);
+                            const drive = await getDriveClient();
+                            const exportRes = await drive.files.export({ fileId: args.documentId, mimeType: 'text/plain' }, { responseType: 'text' });
+                            const textContent = exportRes.data;
+                            if (!textContent?.trim())
+                                return 'Document found, but appears empty.';
+                            if (args.maxLength && textContent.length > args.maxLength) {
+                                return `Content (truncated to ${args.maxLength} chars of ${textContent.length} total):\n---\n${textContent.substring(0, args.maxLength)}\n\n... [Document continues. Use maxLength parameter to adjust limit or remove it to get full content.]`;
+                            }
+                            return `Content (${textContent.length} characters):\n---\n${textContent}`;
+                        }
+                        catch (exportError) {
+                            log.error(`Drive export fallback also failed: ${exportError.message}`);
+                        }
+                    }
+                    throw new UserError(`Permission denied for doc (ID: ${args.documentId}). The Google Docs API may be restricted by your Workspace admin.`);
+                }
+                // Extract detailed error information from Google API response
+                const errorDetails = error.response?.data?.error?.message || error.message || 'Unknown error';
+                const errorCode = error.response?.data?.error?.code || error.code;
+                throw new UserError(`Failed to read doc: ${errorDetails}${errorCode ? ` (Code: ${errorCode})` : ''}`);
+            }
+        },
+    });
+}

package/dist/tools/docs/renameTab.js

@@ -0,0 +1,47 @@
+import { UserError } from 'fastmcp';
+import { z } from 'zod';
+import { getDocsClient } from '../../clients.js';
+import { DocumentIdParameter } from '../../types.js';
+import * as GDocsHelpers from '../../googleDocsApiHelpers.js';
+export function register(server) {
+    server.addTool({
+        name: 'renameTab',
+        description: 'Renames a tab in a Google Docs document. Use listDocumentTabs to get tab IDs first.',
+        parameters: DocumentIdParameter.extend({
+            tabId: z
+                .string()
+                .describe('The ID of the tab to rename. Use listDocumentTabs to get tab IDs.'),
+            newTitle: z.string().min(1).describe('The new title for the tab.'),
+        }),
+        execute: async (args, { log }) => {
+            const docs = await getDocsClient();
+            log.info(`Renaming tab ${args.tabId} to "${args.newTitle}" in doc ${args.documentId}`);
+            try {
+                // Verify the tab exists
+                const targetTab = await GDocsHelpers.getDocumentTab(docs, args.documentId, args.tabId);
+                await GDocsHelpers.executeBatchUpdate(docs, args.documentId, [
+                    {
+                        updateDocumentTabProperties: {
+                            tabProperties: {
+                                tabId: args.tabId,
+                                title: args.newTitle,
+                            },
+                            fields: 'title',
+                        },
+                    },
+                ]);
+                return `Successfully renamed tab "${args.tabId}" to "${args.newTitle}".`;
+            }
+            catch (error) {
+                log.error(`Error renaming tab in doc ${args.documentId}: ${error.message || error}`);
+                if (error instanceof UserError)
+                    throw error;
+                if (error.code === 404)
+                    throw new UserError(`Document not found (ID: ${args.documentId}).`);
+                if (error.code === 403)
+                    throw new UserError(`Permission denied for document (ID: ${args.documentId}).`);
+                throw new UserError(`Failed to rename tab: ${error.message || 'Unknown error'}`);
+            }
+        },
+    });
+}

package/dist/tools/docs/replaceTableRowData.js

@@ -0,0 +1,55 @@
+import { UserError } from 'fastmcp';
+import { z } from 'zod';
+import { getDocsClient } from '../../clients.js';
+import { DocumentIdParameter } from '../../types.js';
+import { getTableById } from './structureHelpers.js';
+import { replaceTableRowData as replaceTableRowDataInternal } from './tableRowDataHelpers.js';
+import { TABLE_CONTENT_INDEXED_BODY_FIELDS, buildDocumentGetFields } from './tabFieldMasks.js';
+export function register(server) {
+    server.addTool({
+        name: 'replaceTableRowData',
+        description: 'Replaces the plain-text contents of a single row in an existing Google Docs table while preserving the table structure and formatting.',
+        parameters: DocumentIdParameter.extend({
+            tableId: z
+                .string()
+                .min(1)
+                .describe('The MCP table ID returned by listDocumentTables, for example "table:body:0".'),
+            rowIndex: z.number().int().min(0).describe('Zero-based row index to replace.'),
+            values: z
+                .array(z.string())
+                .max(50)
+                .describe('Plain-text values to place into the row cells from left to right.'),
+            tabId: z
+                .string()
+                .optional()
+                .describe('The ID of the specific tab containing the table. If not specified, uses the first tab or legacy document body.'),
+        }),
+        execute: async (args, { log }) => {
+            const docs = await getDocsClient();
+            log.info(`Replacing row ${args.rowIndex} in ${args.tableId} for doc ${args.documentId}${args.tabId ? ` (tab: ${args.tabId})` : ''}`);
+            try {
+                const res = await docs.documents.get({
+                    documentId: args.documentId,
+                    ...(args.tabId && { includeTabsContent: true }),
+                    fields: buildDocumentGetFields(TABLE_CONTENT_INDEXED_BODY_FIELDS, args.tabId),
+                });
+                const table = getTableById(res.data, args.tableId, args.tabId);
+                if (!table) {
+                    throw new UserError(`Table "${args.tableId}" not found in document.`);
+                }
+                await replaceTableRowDataInternal(docs, args.documentId, table, args.rowIndex, args.values, args.tabId);
+                return `Successfully replaced row ${args.rowIndex} in table ${args.tableId}.`;
+            }
+            catch (error) {
+                log.error(`Error replacing row ${args.rowIndex} in ${args.tableId} for doc ${args.documentId}: ${error.message || error}`);
+                if (error instanceof UserError)
+                    throw error;
+                if (error.code === 404)
+                    throw new UserError(`Document not found (ID: ${args.documentId}).`);
+                if (error.code === 403)
+                    throw new UserError(`Permission denied for document (ID: ${args.documentId}).`);
+                throw new UserError(`Failed to replace table row data: ${error.message || 'Unknown error'}`);
+            }
+        },
+    });
+}

package/dist/tools/docs/smartChipHelpers.js

@@ -0,0 +1,71 @@
+import * as GDocsHelpers from '../../googleDocsApiHelpers.js';
+function getContentSource(doc, tabId) {
+    if (tabId) {
+        const targetTab = GDocsHelpers.findTabById(doc, tabId);
+        if (!targetTab?.documentTab?.body?.content)
+            return [];
+        return targetTab.documentTab.body.content;
+    }
+    if (doc.body?.content)
+        return doc.body.content;
+    if (doc.tabs?.[0]?.documentTab?.body?.content)
+        return doc.tabs[0].documentTab.body.content;
+    return [];
+}
+function visitContent(content, out) {
+    for (const element of content) {
+        for (const paragraphElement of element.paragraph?.elements ?? []) {
+            if (paragraphElement.dateElement) {
+                out.push({
+                    type: 'date',
+                    startIndex: paragraphElement.startIndex ?? null,
+                    endIndex: paragraphElement.endIndex ?? null,
+                    text: paragraphElement.dateElement.dateElementProperties?.displayText ?? null,
+                    properties: {
+                        dateId: paragraphElement.dateElement.dateId ?? null,
+                        ...paragraphElement.dateElement.dateElementProperties,
+                    },
+                });
+            }
+            if (paragraphElement.richLink) {
+                out.push({
+                    type: 'richLink',
+                    startIndex: paragraphElement.startIndex ?? null,
+                    endIndex: paragraphElement.endIndex ?? null,
+                    text: paragraphElement.richLink.richLinkProperties?.title ?? null,
+                    properties: {
+                        richLinkId: paragraphElement.richLink.richLinkId ?? null,
+                        ...paragraphElement.richLink.richLinkProperties,
+                    },
+                });
+            }
+            if (paragraphElement.person) {
+                out.push({
+                    type: 'person',
+                    startIndex: paragraphElement.startIndex ?? null,
+                    endIndex: paragraphElement.endIndex ?? null,
+                    text: paragraphElement.person.personProperties?.name ??
+                        paragraphElement.person.personProperties?.email ??
+                        null,
+                    properties: {
+                        personId: paragraphElement.person.personId ?? null,
+                        ...paragraphElement.person.personProperties,
+                    },
+                });
+            }
+        }
+        if (element.table?.tableRows) {
+            for (const row of element.table.tableRows) {
+                for (const cell of row.tableCells ?? []) {
+                    visitContent(cell.content ?? [], out);
+                }
+            }
+        }
+    }
+}
+export function extractSmartChips(doc, tabId) {
+    const content = getContentSource(doc, tabId);
+    const chips = [];
+    visitContent(content, chips);
+    return chips;
+}

package/dist/tools/docs/structureHelpers.js

@@ -0,0 +1,250 @@
+import * as GDocsHelpers from '../../googleDocsApiHelpers.js';
+function getContentSource(doc, tabId) {
+    if (tabId) {
+        const targetTab = GDocsHelpers.findTabById(doc, tabId);
+        if (!targetTab?.documentTab?.body?.content) {
+            return [];
+        }
+        return targetTab.documentTab.body.content;
+    }
+    if (doc.body?.content) {
+        return doc.body.content;
+    }
+    if (doc.tabs?.[0]?.documentTab?.body?.content) {
+        return doc.tabs[0].documentTab.body.content;
+    }
+    return [];
+}
+function extractParagraphText(paragraph) {
+    return (paragraph?.elements
+        ?.map((element) => element.textRun?.content ?? '')
+        .join('')
+        .replace(/\n+$/g, '') ?? '');
+}
+function extractCellText(content = []) {
+    const parts = [];
+    for (const element of content) {
+        if (element.paragraph) {
+            const text = extractParagraphText(element.paragraph);
+            if (text)
+                parts.push(text);
+        }
+        if (element.table?.tableRows) {
+            for (const row of element.table.tableRows) {
+                for (const cell of row.tableCells ?? []) {
+                    const text = extractCellText(cell.content ?? []);
+                    if (text)
+                        parts.push(text);
+                }
+            }
+        }
+    }
+    return parts.join('\n').trim();
+}
+function extractCellContentRange(content = []) {
+    let minStart = null;
+    let maxEnd = null;
+    const visitContent = (elements) => {
+        for (const element of elements) {
+            for (const paragraphElement of element.paragraph?.elements ?? []) {
+                const startIndex = paragraphElement.startIndex;
+                if (typeof startIndex === 'number') {
+                    minStart = minStart === null ? startIndex : Math.min(minStart, startIndex);
+                }
+                const endIndex = paragraphElement.endIndex;
+                if (typeof endIndex === 'number') {
+                    maxEnd = maxEnd === null ? endIndex : Math.max(maxEnd, endIndex);
+                }
+            }
+            if (element.table?.tableRows) {
+                for (const row of element.table.tableRows) {
+                    for (const cell of row.tableCells ?? []) {
+                        visitContent(cell.content ?? []);
+                    }
+                }
+            }
+        }
+    };
+    visitContent(content);
+    return {
+        contentStartIndex: minStart,
+        contentEndIndex: maxEnd,
+    };
+}
+function dimensionToPt(dimension) {
+    if (!dimension?.magnitude || dimension.unit !== 'PT')
+        return undefined;
+    return dimension.magnitude;
+}
+function normalizeCellStyle(rowIndex, columnIndex, cell) {
+    const style = cell.tableCellStyle;
+    const firstParagraphHasBoldText = (cell.content ?? []).some((element) => (element.paragraph?.elements ?? []).some((paragraphElement) => paragraphElement.textRun?.textStyle?.bold));
+    if (!style && !firstParagraphHasBoldText)
+        return null;
+    const contentAlignment = style?.contentAlignment === 'TOP' ||
+        style?.contentAlignment === 'MIDDLE' ||
+        style?.contentAlignment === 'BOTTOM' ||
+        style?.contentAlignment === 'CONTENT_ALIGNMENT_UNSPECIFIED'
+        ? style.contentAlignment
+        : null;
+    return {
+        rowIndex,
+        columnIndex,
+        backgroundColor: style?.backgroundColor?.color?.rgbColor ?? undefined,
+        contentAlignment,
+        paddingTopPt: dimensionToPt(style?.paddingTop),
+        paddingBottomPt: dimensionToPt(style?.paddingBottom),
+        paddingLeftPt: dimensionToPt(style?.paddingLeft),
+        paddingRightPt: dimensionToPt(style?.paddingRight),
+        borderTop: style?.borderTop ?? undefined,
+        borderBottom: style?.borderBottom ?? undefined,
+        borderLeft: style?.borderLeft ?? undefined,
+        borderRight: style?.borderRight ?? undefined,
+        hasBoldText: firstParagraphHasBoldText || undefined,
+    };
+}
+export function extractDocumentTables(doc, tabId) {
+    const content = getContentSource(doc, tabId);
+    const tables = [];
+    const tabKey = tabId ?? 'body';
+    for (const element of content) {
+        if (!element.table?.tableRows)
+            continue;
+        const ordinal = tables.length;
+        const cells = [];
+        let columnCount = 0;
+        element.table.tableRows.forEach((row, rowIndex) => {
+            const rowCells = row.tableCells ?? [];
+            columnCount = Math.max(columnCount, rowCells.length);
+            rowCells.forEach((cell, columnIndex) => {
+                const { contentStartIndex, contentEndIndex } = extractCellContentRange(cell.content ?? []);
+                cells.push({
+                    rowIndex,
+                    columnIndex,
+                    startIndex: cell.startIndex ?? null,
+                    endIndex: cell.endIndex ?? null,
+                    contentStartIndex,
+                    contentEndIndex,
+                    text: extractCellText(cell.content ?? []),
+                });
+            });
+        });
+        tables.push({
+            tableId: `table:${tabKey}:${ordinal}`,
+            ordinal,
+            startIndex: element.startIndex ?? null,
+            endIndex: element.endIndex ?? null,
+            rowCount: element.table.tableRows.length,
+            columnCount,
+            cells,
+        });
+    }
+    return tables;
+}
+export function getTableById(doc, tableId, tabId) {
+    return extractDocumentTables(doc, tabId).find((table) => table.tableId === tableId) ?? null;
+}
+export function findTableNearestStartIndex(doc, insertionIndex, tabId) {
+    const tables = extractDocumentTables(doc, tabId).filter((table) => typeof table.startIndex === 'number' && table.startIndex >= insertionIndex);
+    if (tables.length === 0)
+        return null;
+    return tables.sort((a, b) => a.startIndex - b.startIndex)[0] ?? null;
+}
+export function extractTableSnapshot(doc, tableId, tabId) {
+    const content = getContentSource(doc, tabId);
+    const tabKey = tabId ?? 'body';
+    let ordinal = 0;
+    for (const element of content) {
+        if (!element.table?.tableRows)
+            continue;
+        const currentTableId = `table:${tabKey}:${ordinal}`;
+        ordinal++;
+        if (currentTableId !== tableId)
+            continue;
+        const data = [];
+        const rowStyles = [];
+        const cellStyles = [];
+        let pinnedHeaderRowsCount = 0;
+        element.table.tableRows.forEach((row, rowIndex) => {
+            const rowData = [];
+            const rowStyle = row.tableRowStyle;
+            if (rowStyle) {
+                rowStyles.push({
+                    rowIndex,
+                    minRowHeightPt: dimensionToPt(rowStyle.minRowHeight),
+                    preventOverflow: rowStyle.preventOverflow ?? undefined,
+                    tableHeader: rowStyle.tableHeader ?? undefined,
+                });
+            }
+            if ((rowStyle?.tableHeader ?? false) && pinnedHeaderRowsCount === rowIndex) {
+                pinnedHeaderRowsCount++;
+            }
+            (row.tableCells ?? []).forEach((cell, columnIndex) => {
+                rowData.push(extractCellText(cell.content ?? []));
+                const cellStyle = normalizeCellStyle(rowIndex, columnIndex, cell);
+                if (cellStyle)
+                    cellStyles.push(cellStyle);
+            });
+            data.push(rowData);
+        });
+        const columnStyles = element.table.tableStyle?.tableColumnProperties?.map((column, columnIndex) => ({
+            columnIndex,
+            widthPt: dimensionToPt(column.width),
+            widthType: column.widthType,
+        })) ?? [];
+        return {
+            tableId: currentTableId,
+            startIndex: element.startIndex ?? null,
+            endIndex: element.endIndex ?? null,
+            rowCount: element.table.rows ?? data.length,
+            columnCount: element.table.columns ?? Math.max(...data.map((row) => row.length), 0),
+            data,
+            columnStyles,
+            rowStyles,
+            cellStyles,
+            pinnedHeaderRowsCount,
+        };
+    }
+    return null;
+}
+export function findHeadings(doc, headings, tabId) {
+    const content = getContentSource(doc, tabId);
+    const normalizedTargets = new Set(headings.map((heading) => heading.trim()));
+    const tables = extractDocumentTables(doc, tabId);
+    const results = [];
+    let seenTables = 0;
+    for (let index = 0; index < content.length; index++) {
+        const element = content[index];
+        if (element.table?.tableRows) {
+            seenTables++;
+            continue;
+        }
+        const namedStyleType = element.paragraph?.paragraphStyle?.namedStyleType;
+        if (!namedStyleType || !namedStyleType.startsWith('HEADING_'))
+            continue;
+        const headingText = extractParagraphText(element.paragraph).trim();
+        if (!normalizedTargets.has(headingText))
+            continue;
+        let tableIdFollowing;
+        for (let nextIndex = index + 1; nextIndex < content.length; nextIndex++) {
+            const nextElement = content[nextIndex];
+            if (nextElement.table?.tableRows) {
+                tableIdFollowing = tables[seenTables]?.tableId;
+                break;
+            }
+            if (nextElement.paragraph) {
+                const nextStyle = nextElement.paragraph.paragraphStyle?.namedStyleType;
+                if (nextStyle?.startsWith('HEADING_'))
+                    break;
+            }
+        }
+        results.push({
+            headingText,
+            headingLevel: namedStyleType,
+            startIndex: element.startIndex ?? null,
+            endIndex: element.endIndex ?? null,
+            tableIdFollowing,
+        });
+    }
+    return results;
+}

package/dist/tools/docs/tabFieldMasks.js

@@ -0,0 +1,48 @@
+export const TAB_ID_PROPERTIES = 'tabProperties(tabId)';
+export const TAB_LIST_PROPERTIES = 'tabProperties(tabId,title,index,parentTabId)';
+/**
+ * Builds a tabs field mask that includes childTabs recursion (3 levels deep) so that
+ * findTabById() can locate tabs nested at any depth.
+ *
+ * @param documentTabFields - the documentTab(...) subfields needed, e.g. 'documentTab(body(content(endIndex)))'
+ */
+export function buildTabsFieldMask(documentTabFields) {
+    const child3 = `childTabs(${TAB_ID_PROPERTIES},${documentTabFields})`;
+    const child2 = `childTabs(${TAB_ID_PROPERTIES},${documentTabFields},${child3})`;
+    const child1 = `childTabs(${TAB_ID_PROPERTIES},${documentTabFields},${child2})`;
+    return `tabs(${TAB_ID_PROPERTIES},${documentTabFields},${child1})`;
+}
+const BODY_RANGE = 'documentTab(body(content(startIndex,endIndex)))';
+const BODY_END = 'documentTab(body(content(endIndex)))';
+export const TAB_BODY_RANGE_FIELDS = buildTabsFieldMask(BODY_RANGE);
+export const TAB_BODY_END_INDEX_FIELDS = buildTabsFieldMask(BODY_END);
+const TAB_LIST_CHILD_FIELDS = `childTabs(${TAB_LIST_PROPERTIES},childTabs(${TAB_LIST_PROPERTIES},childTabs(${TAB_LIST_PROPERTIES})))`;
+export const TAB_LIST_FIELDS = `title,tabs(${TAB_LIST_PROPERTIES},${TAB_LIST_CHILD_FIELDS})`;
+export const TAB_LIST_WITH_CONTENT_FIELDS = `title,tabs(${TAB_LIST_PROPERTIES},${TAB_LIST_CHILD_FIELDS},documentTab(body(content(endIndex))))`;
+export const TAB_FIELD_MASKS = {
+    TAB_BODY_RANGE_FIELDS,
+    TAB_BODY_END_INDEX_FIELDS,
+    TAB_LIST_FIELDS,
+    TAB_LIST_WITH_CONTENT_FIELDS,
+};
+// ── Shared body-level field strings for document.get calls ──────────────────
+// Used to build conditional field masks: body fields for legacy (no tabId),
+// or buildTabsFieldMask(`documentTab(${...})`) when a tabId is provided.
+/** Minimal table index fields — rows/cells start+endIndex only. */
+export const TABLE_INDEX_BODY_FIELDS = 'body(content(startIndex,endIndex,table(tableRows(tableCells(startIndex,endIndex)))))';
+/** Table fields with basic cell text (no content indices). */
+export const TABLE_CONTENT_BASIC_BODY_FIELDS = 'body(content(startIndex,endIndex,table(tableRows(tableCells(startIndex,endIndex,content(paragraph(elements(textRun(content)))))))))';
+/** Table fields with full content + element indices (needed for in-cell editing). */
+export const TABLE_CONTENT_INDEXED_BODY_FIELDS = 'body(content(startIndex,endIndex,table(tableRows(tableCells(startIndex,endIndex,content(startIndex,endIndex,paragraph(elements(startIndex,endIndex,textRun(content)))))))))';
+/** Heading + table fields for section-by-heading lookups. */
+export const HEADING_BODY_FIELDS = 'body(content(startIndex,endIndex,paragraph(paragraphStyle(namedStyleType),elements(textRun(content))),table(tableRows(tableCells(startIndex,endIndex,content(paragraph(elements(textRun(content)))))))))';
+/** Smart chip fields (date, person, richLink) in body + table cells. */
+export const SMART_CHIP_BODY_FIELDS = 'body(content(paragraph(elements(startIndex,endIndex,dateElement(dateId,dateElementProperties),richLink(richLinkId,richLinkProperties),person(personId,personProperties))),table(tableRows(tableCells(content(paragraph(elements(startIndex,endIndex,dateElement(dateId,dateElementProperties),richLink(richLinkId,richLinkProperties),person(personId,personProperties)))))))))';
+/**
+ * Returns the correct fields string for a documents.get call.
+ * When tabId is set, wraps bodyFields in a tabs field mask.
+ * When tabId is absent, returns bodyFields directly (legacy body mode).
+ */
+export function buildDocumentGetFields(bodyFields, tabId) {
+    return tabId ? buildTabsFieldMask(`documentTab(${bodyFields})`) : bodyFields;
+}