@divyacon/piece-google-docs 0.0.0-stage → 0.1.0

package/src/lib/actions/delete-footer.action.ts

@@ -0,0 +1,51 @@
+import { googleDocsAuth, createGoogleClient } from '../auth';
+import { docsCommon } from '../common';
+import { Property, createAction } from '@agnocon/pieces-framework';
+import { docs as googleDocs, docs_v1 } from '@googleapis/docs';
+import { deleteFooterActionOutputSchema } from '../output-schemas';
+
+export const deleteFooter = createAction({
+  auth: googleDocsAuth,
+  name: 'delete_footer',
+  displayName: 'Delete Footer',
+  description: 'Delete a footer from a Google Docs document',
+  audience: 'ai',
+  aiMetadata: {
+    description:
+      'Permanently deletes a footer section from a Google Docs document by its footer ID. The footer ID is a hidden identifier — obtain it from the Read Document (gdocs_get_document) response under the document\'s named styles or sections; it cannot be guessed. Destructive and not idempotent: the footer content is unrecoverable once deleted.',
+    idempotent: false,
+  },
+  outputSchema: deleteFooterActionOutputSchema,
+  props: {
+    documentId: Property.ShortText({
+      displayName: 'Document ID',
+      description: 'The ID of the document to edit.',
+      required: true,
+    }),
+    footerId: Property.ShortText({
+      displayName: 'Footer ID',
+      description: 'The ID of the footer to delete. Obtain from Read Document (gdocs_get_document) — cannot be guessed.',
+      required: true,
+    }),
+  },
+  async run(context) {
+    const { documentId, footerId } = context.propsValue;
+
+    const authClient = await createGoogleClient(context.auth);
+    const docs = googleDocs({ version: 'v1', auth: authClient });
+
+    const request: docs_v1.Schema$Request = {
+      deleteFooter: { footerId },
+    };
+
+    try {
+      await docs.documents.batchUpdate({
+        documentId,
+        requestBody: { requests: [request] },
+      });
+      return { success: true, documentId, deletedFooterId: footerId };
+    } catch (error) {
+      throw new Error(docsCommon.formatError(error, 'delete the footer from'));
+    }
+  },
+});

package/src/lib/actions/delete-header.action.ts

@@ -0,0 +1,51 @@
+import { googleDocsAuth, createGoogleClient } from '../auth';
+import { docsCommon } from '../common';
+import { Property, createAction } from '@agnocon/pieces-framework';
+import { docs as googleDocs, docs_v1 } from '@googleapis/docs';
+import { deleteHeaderActionOutputSchema } from '../output-schemas';
+
+export const deleteHeader = createAction({
+  auth: googleDocsAuth,
+  name: 'delete_header',
+  displayName: 'Delete Header',
+  description: 'Delete a header from a Google Docs document',
+  audience: 'ai',
+  aiMetadata: {
+    description:
+      'Permanently deletes a header section from a Google Docs document by its header ID. The header ID is a hidden identifier — obtain it from the Read Document (gdocs_get_document) response under the document\'s named styles or sections; it cannot be guessed. Destructive and not idempotent: the header content is unrecoverable once deleted.',
+    idempotent: false,
+  },
+  outputSchema: deleteHeaderActionOutputSchema,
+  props: {
+    documentId: Property.ShortText({
+      displayName: 'Document ID',
+      description: 'The ID of the document to edit.',
+      required: true,
+    }),
+    headerId: Property.ShortText({
+      displayName: 'Header ID',
+      description: 'The ID of the header to delete. Obtain from Read Document (gdocs_get_document) — cannot be guessed.',
+      required: true,
+    }),
+  },
+  async run(context) {
+    const { documentId, headerId } = context.propsValue;
+
+    const authClient = await createGoogleClient(context.auth);
+    const docs = googleDocs({ version: 'v1', auth: authClient });
+
+    const request: docs_v1.Schema$Request = {
+      deleteHeader: { headerId },
+    };
+
+    try {
+      await docs.documents.batchUpdate({
+        documentId,
+        requestBody: { requests: [request] },
+      });
+      return { success: true, documentId, deletedHeaderId: headerId };
+    } catch (error) {
+      throw new Error(docsCommon.formatError(error, 'delete the header from'));
+    }
+  },
+});

package/src/lib/actions/delete-named-range.action.ts

@@ -0,0 +1,65 @@
+import { googleDocsAuth, createGoogleClient } from '../auth';
+import { docsCommon } from '../common';
+import { Property, createAction } from '@agnocon/pieces-framework';
+import { docs as googleDocs, docs_v1 } from '@googleapis/docs';
+import { deleteNamedRangeActionOutputSchema } from '../output-schemas';
+
+export const deleteNamedRange = createAction({
+  auth: googleDocsAuth,
+  name: 'delete_named_range',
+  displayName: 'Delete Named Range',
+  description: 'Delete a named range from a Google Docs document by ID or name',
+  audience: 'ai',
+  aiMetadata: {
+    description:
+      'Deletes a named range from a Google Docs document. Provide either namedRangeId (targets one specific range — obtain from Read Document gdocs_get_document, cannot be guessed) or name (deletes all named ranges with that name). Re-deleting an already-gone range or name is a no-op, so this call is idempotent.',
+    idempotent: true,
+  },
+  outputSchema: deleteNamedRangeActionOutputSchema,
+  props: {
+    documentId: Property.ShortText({
+      displayName: 'Document ID',
+      description: 'The ID of the document to edit.',
+      required: true,
+    }),
+    namedRangeId: Property.ShortText({
+      displayName: 'Named Range ID',
+      description: 'The ID of the named range to delete. Obtain from Read Document (gdocs_get_document) — cannot be guessed. Provide this OR Name, not both.',
+      required: false,
+    }),
+    name: Property.ShortText({
+      displayName: 'Name',
+      description: 'The name of the named range(s) to delete. All ranges with this name will be removed. Provide this OR Named Range ID, not both.',
+      required: false,
+    }),
+  },
+  async run(context) {
+    const { documentId, namedRangeId, name } = context.propsValue;
+
+    if (!namedRangeId && !name) {
+      throw new Error('Provide either Named Range ID or Name — at least one is required.');
+    }
+
+    const authClient = await createGoogleClient(context.auth);
+    const docs = googleDocs({ version: 'v1', auth: authClient });
+
+    const request: docs_v1.Schema$Request = namedRangeId
+      ? { deleteNamedRange: { namedRangeId } }
+      : { deleteNamedRange: { name } };
+
+    try {
+      await docs.documents.batchUpdate({
+        documentId,
+        requestBody: { requests: [request] },
+      });
+      return {
+        success: true,
+        documentId,
+        deletedNamedRangeId: namedRangeId ?? null,
+        deletedName: name ?? null,
+      };
+    } catch (error) {
+      throw new Error(docsCommon.formatError(error, 'delete the named range from'));
+    }
+  },
+});

package/src/lib/actions/delete-paragraph-bullets.action.ts

@@ -0,0 +1,62 @@
+import { googleDocsAuth, createGoogleClient } from '../auth';
+import { docsCommon } from '../common';
+import { Property, createAction } from '@agnocon/pieces-framework';
+import { docs as googleDocs, docs_v1 } from '@googleapis/docs';
+import { deleteParagraphBulletsActionOutputSchema } from '../output-schemas';
+
+export const deleteParagraphBullets = createAction({
+  auth: googleDocsAuth,
+  name: 'delete_paragraph_bullets',
+  displayName: 'Delete Paragraph Bullets',
+  description: 'Remove bullet list formatting from paragraphs in a range of a Google Docs document',
+  audience: 'ai',
+  aiMetadata: {
+    description:
+      'Removes bullet or numbered list formatting from all paragraphs within the given character index range in a Google Docs document. The paragraphs\' text content is preserved; only the list nesting and bullet glyphs are removed. Obtain valid startIndex and endIndex from Get Document End Index (gdocs_get_document_end_index) — indices cannot be guessed. Idempotent: re-running on already plain paragraphs is a no-op.',
+    idempotent: true,
+  },
+  outputSchema: deleteParagraphBulletsActionOutputSchema,
+  props: {
+    documentId: Property.ShortText({
+      displayName: 'Document ID',
+      description: 'The ID of the document to edit.',
+      required: true,
+    }),
+    startIndex: Property.Number({
+      displayName: 'Start Index',
+      description: 'Inclusive start character index of the range. Obtain from Get Document End Index (gdocs_get_document_end_index).',
+      required: true,
+    }),
+    endIndex: Property.Number({
+      displayName: 'End Index',
+      description: 'Exclusive end character index of the range. Must be greater than Start Index. Obtain from Get Document End Index (gdocs_get_document_end_index).',
+      required: true,
+    }),
+  },
+  async run(context) {
+    const { documentId, startIndex, endIndex } = context.propsValue;
+
+    if (endIndex <= startIndex) {
+      throw new Error('End Index must be greater than Start Index.');
+    }
+
+    const authClient = await createGoogleClient(context.auth);
+    const docs = googleDocs({ version: 'v1', auth: authClient });
+
+    const request: docs_v1.Schema$Request = {
+      deleteParagraphBullets: {
+        range: { startIndex, endIndex },
+      },
+    };
+
+    try {
+      await docs.documents.batchUpdate({
+        documentId,
+        requestBody: { requests: [request] },
+      });
+      return { success: true, documentId, rangeStart: startIndex, rangeEnd: endIndex };
+    } catch (error) {
+      throw new Error(docsCommon.formatError(error, 'delete paragraph bullets from'));
+    }
+  },
+});

package/src/lib/actions/delete-table-column.action.ts

@@ -0,0 +1,67 @@
+import { googleDocsAuth, createGoogleClient } from '../auth';
+import { docsCommon } from '../common';
+import { Property, createAction } from '@agnocon/pieces-framework';
+import { docs as googleDocs, docs_v1 } from '@googleapis/docs';
+import { deleteTableColumnActionOutputSchema } from '../output-schemas';
+
+export const deleteTableColumn = createAction({
+  auth: googleDocsAuth,
+  name: 'delete_table_column',
+  displayName: 'Delete Table Column',
+  description: 'Delete a column from a table in a Google Docs document',
+  audience: 'ai',
+  aiMetadata: {
+    description:
+      'Permanently deletes a column from a table in a Google Docs document. The column to delete is addressed by the table\'s start index plus the row and column coordinates of any cell in that column. All three index values (tableStartIndex, rowIndex, columnIndex) must be obtained from Read Document (gdocs_get_document) — they cannot be guessed. Destructive and not idempotent: all content in the column is permanently removed.',
+    idempotent: false,
+  },
+  outputSchema: deleteTableColumnActionOutputSchema,
+  props: {
+    documentId: Property.ShortText({
+      displayName: 'Document ID',
+      description: 'The ID of the document to edit.',
+      required: true,
+    }),
+    tableStartIndex: Property.Number({
+      displayName: 'Table Start Index',
+      description: 'The character index of the start of the table in the document body. Obtain from Read Document (gdocs_get_document) — cannot be guessed.',
+      required: true,
+    }),
+    rowIndex: Property.Number({
+      displayName: 'Row Index',
+      description: 'Zero-based row index of any cell in the column to delete. Obtain from Read Document (gdocs_get_document).',
+      required: true,
+    }),
+    columnIndex: Property.Number({
+      displayName: 'Column Index',
+      description: 'Zero-based column index of the column to delete. Obtain from Read Document (gdocs_get_document).',
+      required: true,
+    }),
+  },
+  async run(context) {
+    const { documentId, tableStartIndex, rowIndex, columnIndex } = context.propsValue;
+
+    const authClient = await createGoogleClient(context.auth);
+    const docs = googleDocs({ version: 'v1', auth: authClient });
+
+    const request: docs_v1.Schema$Request = {
+      deleteTableColumn: {
+        tableCellLocation: {
+          tableStartLocation: { index: tableStartIndex },
+          rowIndex,
+          columnIndex,
+        },
+      },
+    };
+
+    try {
+      await docs.documents.batchUpdate({
+        documentId,
+        requestBody: { requests: [request] },
+      });
+      return { success: true, documentId, tableStartIndex, deletedColumnIndex: columnIndex };
+    } catch (error) {
+      throw new Error(docsCommon.formatError(error, 'delete the table column from'));
+    }
+  },
+});

package/src/lib/actions/delete-table-row.action.ts

@@ -0,0 +1,67 @@
+import { googleDocsAuth, createGoogleClient } from '../auth';
+import { docsCommon } from '../common';
+import { Property, createAction } from '@agnocon/pieces-framework';
+import { docs as googleDocs, docs_v1 } from '@googleapis/docs';
+import { deleteTableRowActionOutputSchema } from '../output-schemas';
+
+export const deleteTableRow = createAction({
+  auth: googleDocsAuth,
+  name: 'delete_table_row',
+  displayName: 'Delete Table Row',
+  description: 'Delete a row from a table in a Google Docs document',
+  audience: 'ai',
+  aiMetadata: {
+    description:
+      'Permanently deletes a row from a table in a Google Docs document. The row to delete is addressed by the table\'s start index plus the row and column coordinates of any cell in that row. All three index values (tableStartIndex, rowIndex, columnIndex) must be obtained from Read Document (gdocs_get_document) — they cannot be guessed. Destructive and not idempotent: all content in the row is permanently removed.',
+    idempotent: false,
+  },
+  outputSchema: deleteTableRowActionOutputSchema,
+  props: {
+    documentId: Property.ShortText({
+      displayName: 'Document ID',
+      description: 'The ID of the document to edit.',
+      required: true,
+    }),
+    tableStartIndex: Property.Number({
+      displayName: 'Table Start Index',
+      description: 'The character index of the start of the table in the document body. Obtain from Read Document (gdocs_get_document) — cannot be guessed.',
+      required: true,
+    }),
+    rowIndex: Property.Number({
+      displayName: 'Row Index',
+      description: 'Zero-based row index of the row to delete. Obtain from Read Document (gdocs_get_document).',
+      required: true,
+    }),
+    columnIndex: Property.Number({
+      displayName: 'Column Index',
+      description: 'Zero-based column index of any cell in the row to delete. Obtain from Read Document (gdocs_get_document).',
+      required: true,
+    }),
+  },
+  async run(context) {
+    const { documentId, tableStartIndex, rowIndex, columnIndex } = context.propsValue;
+
+    const authClient = await createGoogleClient(context.auth);
+    const docs = googleDocs({ version: 'v1', auth: authClient });
+
+    const request: docs_v1.Schema$Request = {
+      deleteTableRow: {
+        tableCellLocation: {
+          tableStartLocation: { index: tableStartIndex },
+          rowIndex,
+          columnIndex,
+        },
+      },
+    };
+
+    try {
+      await docs.documents.batchUpdate({
+        documentId,
+        requestBody: { requests: [request] },
+      });
+      return { success: true, documentId, tableStartIndex, deletedRowIndex: rowIndex };
+    } catch (error) {
+      throw new Error(docsCommon.formatError(error, 'delete the table row from'));
+    }
+  },
+});

package/src/lib/actions/export-as-pdf.action.ts

@@ -0,0 +1,59 @@
+import { googleDocsAuth, createGoogleClient } from '../auth';
+import { docsCommon } from '../common';
+import { Property, createAction } from '@agnocon/pieces-framework';
+import { drive as googleDrive } from '@googleapis/drive';
+import { docs as googleDocs } from '@googleapis/docs';
+import { exportAsPdfActionOutputSchema } from '../output-schemas';
+
+export const exportAsPdf = createAction({
+	auth: googleDocsAuth,
+	name: 'export_as_pdf',
+	displayName: 'Export as PDF',
+	description: 'Export a Google Docs document as a PDF file.',
+	audience: 'ai',
+	aiMetadata: {
+		description:
+			'Exports a Google Docs document as a PDF and returns the file for use in later steps (e.g. sending via email or uploading to storage). Uses the Drive export endpoint, so the document must not exceed the Drive 10 MB export limit. Read-only and idempotent — it never modifies the document.',
+		idempotent: true,
+	},
+	outputSchema: exportAsPdfActionOutputSchema,
+	props: {
+		documentId: Property.ShortText({
+			displayName: 'Document ID',
+			description: 'The ID of the document to export as PDF.',
+			required: true,
+		}),
+	},
+	async run(context) {
+		const { documentId } = context.propsValue;
+		const authClient = await createGoogleClient(context.auth);
+
+		// Fetch document title for the file name
+		const docs = googleDocs({ version: 'v1', auth: authClient });
+		let title = documentId;
+		try {
+			const docResponse = await docs.documents.get({ documentId, fields: 'title' });
+			title = docResponse.data.title ?? documentId;
+		} catch {
+			// Fall back to documentId as the file name if the title fetch fails
+		}
+
+		const drive = googleDrive({ version: 'v3', auth: authClient });
+
+		try {
+			const response = await drive.files.export(
+				{ fileId: documentId, mimeType: 'application/pdf' },
+				{ responseType: 'arraybuffer' }
+			);
+
+			const file = await context.files.write({
+				fileName: `${title}.pdf`,
+				data: Buffer.from(response.data as ArrayBuffer),
+			});
+
+			return { success: true, documentId, file };
+		} catch (error) {
+			throw new Error(docsCommon.formatError(error, 'export'));
+		}
+	},
+});

package/src/lib/actions/find-document.ts

@@ -0,0 +1,136 @@
+import { googleDocsAuth, createGoogleClient } from '../auth';
+import {
+	createAction,
+	DynamicPropsValue,
+	Property,
+} from '@agnocon/pieces-framework';
+import { drive as googleDrive } from '@googleapis/drive';
+import { docs as googleDocs } from '@googleapis/docs';
+import { folderIdProp } from '../common/props';
+import { findDocumentActionOutputSchema } from '../output-schemas';
+
+export const findDocumentAction = createAction({
+	auth: googleDocsAuth,
+	name: 'google-docs-find-document',
+	displayName: 'Find Document',
+	description: 'Search for document by name.',
+	audience: 'human',
+	aiMetadata: {
+		description:
+			'Searches Google Drive for a Google Docs document whose name contains the given text, optionally scoped to a folder, and returns the first match. Use when an agent has a document name but not its ID and needs to resolve it. Idempotent only when used purely for lookup; enabling "Create a new document if not found" makes it create (and optionally move) a new document on each miss, which is a mutating side effect.',
+		idempotent: false,
+	},
+	props: {
+		name: Property.ShortText({
+			displayName: 'Document Name',
+			required: true,
+		}),
+		folderId: folderIdProp,
+		createIfNotFound: Property.Checkbox({
+			displayName: 'Create a new document if not found?',
+			defaultValue: false,
+			required: false,
+		}),
+		newDocumentProps: Property.DynamicProperties({
+			auth: googleDocsAuth,
+			displayName: 'New Document Properties',
+			required: false,
+			refreshers: ['createIfNotFound'],
+			props: async ({ auth, createIfNotFound }) => {
+				if (!auth) return {};
+				if (!createIfNotFound) return {};
+
+				const props: DynamicPropsValue = {};
+
+				if (createIfNotFound) {
+					props['content'] = Property.LongText({
+						displayName: 'Document Content',
+						required: true,
+					});
+				}
+
+				return props;
+			},
+		}),
+	},
+	outputSchema: findDocumentActionOutputSchema,
+	async run(context) {
+		const { name: documentName, folderId, createIfNotFound, newDocumentProps } = context.propsValue;
+		const newDocumentContent = newDocumentProps?.['content'] as string;
+
+		const authClient = await createGoogleClient(context.auth);
+
+		const drive = googleDrive({ version: 'v3', auth: authClient });
+		const docs = googleDocs({ version: 'v1', auth: authClient });
+
+		// Search for the document in Google Drive
+		const query: string[] = [
+			`name contains '${documentName}'`,
+			`mimeType='application/vnd.google-apps.document'`,
+			'trashed=false',
+		];
+
+		if (folderId) query.push(`'${folderId}' in parents`);
+
+		const response = await drive.files.list({
+			q: query.join(' and '),
+			supportsAllDrives: true,
+			fields: '*',
+			pageSize: 1,
+			includeItemsFromAllDrives: true,
+			corpora: 'allDrives',
+		});
+
+		const existingFile = response.data.files?.[0];
+
+		if (existingFile) {
+			return { found: true, file: existingFile };
+		}
+
+		// Create a new document if not found
+		if (!createIfNotFound) return { found: false, file: {} };
+
+		//creating new Document
+		const createdDoc = await docs.documents.create({ requestBody: { title: documentName } });
+		const documentId = createdDoc.data.documentId;
+
+		if (!documentId) throw new Error('Failed to create document');
+
+		// Insert content into the new document
+		if (newDocumentContent) {
+			// appending text
+			await docs.documents.batchUpdate({
+				documentId,
+				requestBody: {
+					requests: [{ insertText: { text: newDocumentContent, endOfSegmentLocation: {} } }],
+				},
+			});
+		}
+
+		// Move the document to the specified folder
+		if (folderId) {
+			const fileData = await drive.files.get({
+				fileId: documentId,
+				supportsAllDrives: true,
+				fields: 'id, parents',
+			});
+
+			await drive.files.update({
+				fileId: documentId,
+				fields: 'id, name, parents',
+				removeParents: fileData.data.parents?.join(','),
+				addParents: folderId,
+				supportsAllDrives: true,
+			});
+		}
+
+		// Fetch document details
+		const finalFile = await drive.files.get({
+			fileId: documentId,
+			supportsAllDrives: true,
+			fields: '*',
+		});
+
+		return { found: false, file: finalFile.data };
+	},
+});

package/src/lib/actions/get-document-end-index.action.ts

@@ -0,0 +1,47 @@
+import { googleDocsAuth, createGoogleClient } from '../auth';
+import { docsCommon } from '../common';
+import { Property, createAction } from '@agnocon/pieces-framework';
+import { docs as googleDocs } from '@googleapis/docs';
+import { getDocumentEndIndexActionOutputSchema } from '../output-schemas';
+
+export const getDocumentEndIndex = createAction({
+  auth: googleDocsAuth,
+  name: 'get_document_end_index',
+  displayName: 'Get Document End Index',
+  description: 'Get the end index of a Google Docs document body',
+  audience: 'ai',
+  aiMetadata: {
+    description:
+      'Returns the end index of a Google Docs document body (the highest character position) so an agent can compute where to insert, delete, or style content. Call this FIRST before any index-based editing atomic (Insert Text with an explicit index, Delete Content Range, etc.) — Google Docs edits are addressed by an integer character index that cannot be guessed. Requires the document ID; read-only and idempotent.',
+    idempotent: true,
+  },
+  outputSchema: getDocumentEndIndexActionOutputSchema,
+  props: {
+    documentId: Property.ShortText({
+      displayName: 'Document ID',
+      description: 'The ID of the document to inspect (from the document URL or Search Documents).',
+      required: true,
+    }),
+  },
+  async run(context) {
+    const { documentId } = context.propsValue;
+    const authClient = await createGoogleClient(context.auth);
+    const docs = googleDocs({ version: 'v1', auth: authClient });
+
+    try {
+      const response = await docs.documents.get({ documentId });
+      const content = response.data.body?.content ?? [];
+      const lastElement = content[content.length - 1];
+      const endIndex = lastElement?.endIndex ?? 1;
+
+      return {
+        documentId,
+        title: response.data.title ?? null,
+        endIndex,
+        maxInsertIndex: Math.max(1, endIndex - 1),
+      };
+    } catch (error) {
+      throw new Error(docsCommon.formatError(error, 'read'));
+    }
+  },
+});

package/src/lib/actions/get-document-plaintext.action.ts

@@ -0,0 +1,74 @@
+import { googleDocsAuth, createGoogleClient } from '../auth';
+import { Property, createAction } from '@agnocon/pieces-framework';
+import { docs as googleDocs, docs_v1 } from '@googleapis/docs';
+import { getDocumentPlaintextActionOutputSchema } from '../output-schemas';
+
+// Minimal prose projection: only top-level body paragraph text runs are
+// flattened. Content inside tables, headers, footers, footnotes, and tabs is
+// intentionally NOT included — keep the contract unambiguous for agents that
+// just want the document prose. Use read_document for the full structural JSON.
+function flattenBodyToPlainText(body: docs_v1.Schema$Body | undefined): string {
+	const lines: string[] = [];
+	for (const element of body?.content ?? []) {
+		const paragraph = element.paragraph;
+		if (!paragraph) continue;
+		const text = (paragraph.elements ?? [])
+			.map((paragraphElement) => paragraphElement.textRun?.content ?? '')
+			.join('');
+		lines.push(text);
+	}
+	return lines.join('').replace(/\n+$/, '');
+}
+
+export const getDocumentPlaintext = createAction({
+	auth: googleDocsAuth,
+	name: 'get_document_plaintext',
+	displayName: 'Get Document Plain Text',
+	description: 'Get the plain text content of a Google Docs document.',
+	audience: 'ai',
+	aiMetadata: {
+		description:
+			'Returns just the body prose of a Google Docs document as a plain string, flattened from the document.get response. Pick this over Read Document when you only need the text to summarize/extract/classify and want to avoid the large nested structural JSON. Only top-level paragraph text is included — tables, headers, footers, footnotes, and tabs are omitted. Read-only and idempotent.',
+		idempotent: true,
+	},
+	outputSchema: getDocumentPlaintextActionOutputSchema,
+	props: {
+		documentId: Property.ShortText({
+			displayName: 'Document ID',
+			description:
+				"The ID of the document to read, found in its URL: 'https://docs.google.com/document/d/<documentId>/edit'. Obtain it from Search Documents or Find Document if you only have a name.",
+			required: true,
+		}),
+	},
+	async run(context) {
+		const authClient = await createGoogleClient(context.auth);
+		const docs = googleDocs({ version: 'v1', auth: authClient });
+
+		try {
+			const response = await docs.documents.get({
+				documentId: context.propsValue.documentId,
+			});
+
+			const plainText = flattenBodyToPlainText(response.data.body);
+
+			return {
+				documentId: response.data.documentId ?? context.propsValue.documentId,
+				title: response.data.title ?? '',
+				plainText,
+			};
+		} catch (e) {
+			const error = e as { code?: number; message?: string };
+			if (error.code === 403) {
+				throw new Error(
+					'Permission denied reading the document. Ensure the connected account has access to this document.'
+				);
+			}
+			if (error.code === 404) {
+				throw new Error(
+					`Document not found for ID '${context.propsValue.documentId}'. Verify the document ID.`
+				);
+			}
+			throw e;
+		}
+	},
+});