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

package/src/lib/actions/update-document-style.action.ts

@@ -0,0 +1,93 @@
+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 { updateDocumentStyleActionOutputSchema } from '../output-schemas';
+
+export const updateDocumentStyle = createAction({
+	auth: googleDocsAuth,
+	name: 'update_document_style',
+	displayName: 'Update Document Style',
+	description: 'Update the page margins or other document-level style properties of a Google Docs document.',
+	audience: 'ai',
+	aiMetadata: {
+		description:
+			'Updates document-level style properties such as page margins. Only the properties you provide are changed — leave any margin empty to leave it unchanged. Re-applying the same values leaves the document in the same state, so it is idempotent. Use this to set consistent page margins before exporting or sharing a document.',
+		idempotent: true,
+	},
+	outputSchema: updateDocumentStyleActionOutputSchema,
+	props: {
+		documentId: Property.ShortText({
+			displayName: 'Document ID',
+			description: 'The ID of the document whose style to update.',
+			required: true,
+		}),
+		marginTopPt: Property.Number({
+			displayName: 'Top Margin (pt)',
+			description: 'Top page margin in points. Leave empty to keep the current value.',
+			required: false,
+		}),
+		marginBottomPt: Property.Number({
+			displayName: 'Bottom Margin (pt)',
+			description: 'Bottom page margin in points. Leave empty to keep the current value.',
+			required: false,
+		}),
+		marginLeftPt: Property.Number({
+			displayName: 'Left Margin (pt)',
+			description: 'Left page margin in points. Leave empty to keep the current value.',
+			required: false,
+		}),
+		marginRightPt: Property.Number({
+			displayName: 'Right Margin (pt)',
+			description: 'Right page margin in points. Leave empty to keep the current value.',
+			required: false,
+		}),
+	},
+	async run(context) {
+		const { documentId, marginTopPt, marginBottomPt, marginLeftPt, marginRightPt } = context.propsValue;
+
+		const documentStyle: docs_v1.Schema$DocumentStyle = {};
+		const fieldPaths: string[] = [];
+
+		if (marginTopPt !== undefined && marginTopPt !== null) {
+			documentStyle.marginTop = { magnitude: marginTopPt, unit: 'PT' };
+			fieldPaths.push('marginTop');
+		}
+		if (marginBottomPt !== undefined && marginBottomPt !== null) {
+			documentStyle.marginBottom = { magnitude: marginBottomPt, unit: 'PT' };
+			fieldPaths.push('marginBottom');
+		}
+		if (marginLeftPt !== undefined && marginLeftPt !== null) {
+			documentStyle.marginLeft = { magnitude: marginLeftPt, unit: 'PT' };
+			fieldPaths.push('marginLeft');
+		}
+		if (marginRightPt !== undefined && marginRightPt !== null) {
+			documentStyle.marginRight = { magnitude: marginRightPt, unit: 'PT' };
+			fieldPaths.push('marginRight');
+		}
+
+		if (fieldPaths.length === 0) {
+			throw new Error('At least one style property must be provided.');
+		}
+
+		const request: docs_v1.Schema$Request = {
+			updateDocumentStyle: {
+				documentStyle,
+				fields: fieldPaths.join(','),
+			},
+		};
+
+		const authClient = await createGoogleClient(context.auth);
+		const docs = googleDocs({ version: 'v1', auth: authClient });
+
+		try {
+			await docs.documents.batchUpdate({
+				documentId,
+				requestBody: { requests: [request] },
+			});
+			return { success: true, documentId, updatedFields: fieldPaths };
+		} catch (error) {
+			throw new Error(docsCommon.formatError(error, 'update the style of'));
+		}
+	},
+});

package/src/lib/actions/update-table-row-style.action.ts

@@ -0,0 +1,73 @@
+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 { updateTableRowStyleActionOutputSchema } from '../output-schemas';
+
+export const updateTableRowStyle = createAction({
+  auth: googleDocsAuth,
+  name: 'update_table_row_style',
+  displayName: 'Update Table Row Style',
+  description: 'Update style properties of one or more rows in a Google Docs table',
+  audience: 'ai',
+  aiMetadata: {
+    description:
+      'Updates the minimum height of one or more rows in a Google Docs table. Requires the table start index from Read Document — cannot be guessed. (Google Docs does not support toggling a header row via this request.) Idempotent: applying the same height again is a no-op.',
+    idempotent: true,
+  },
+  outputSchema: updateTableRowStyleActionOutputSchema,
+  props: {
+    documentId: Property.ShortText({
+      displayName: 'Document ID',
+      description: 'The ID of the document containing the table.',
+      required: true,
+    }),
+    tableStartIndex: Property.Number({
+      displayName: 'Table Start Index',
+      description: 'Obtain the table start index from Read Document — cannot be guessed.',
+      required: true,
+    }),
+    rowIndices: Property.Array({
+      displayName: 'Row Indices',
+      description: 'Zero-based indices of the rows to update (e.g. [0, 1] to update the first two rows).',
+      required: true,
+    }),
+    minRowHeightPt: Property.Number({
+      displayName: 'Minimum Row Height (points)',
+      description: 'Minimum height of each selected row, in points.',
+      required: true,
+    }),
+  },
+  async run(context) {
+    const { documentId, tableStartIndex, rowIndices, minRowHeightPt } = context.propsValue;
+    const authClient = await createGoogleClient(context.auth);
+    const docs = googleDocs({ version: 'v1', auth: authClient });
+
+    const rowIndexNumbers = (rowIndices as unknown[]).map((v) => Number(v));
+
+    const request: docs_v1.Schema$Request = {
+      updateTableRowStyle: {
+        tableStartLocation: { index: tableStartIndex },
+        rowIndices: rowIndexNumbers,
+        tableRowStyle: { minRowHeight: { magnitude: minRowHeightPt, unit: 'PT' } },
+        fields: 'minRowHeight',
+      },
+    };
+
+    try {
+      await docs.documents.batchUpdate({
+        documentId,
+        requestBody: { requests: [request] },
+      });
+      return {
+        success: true,
+        documentId,
+        tableStartIndex,
+        rowIndices: rowIndexNumbers,
+        updatedFields: ['minRowHeight'],
+      };
+    } catch (error) {
+      throw new Error(docsCommon.formatError(error, 'update table row style in'));
+    }
+  },
+});

package/src/lib/auth.ts

@@ -0,0 +1,84 @@
+import { AppConnectionValueForAuthProperty, PieceAuth, Property } from '@agnocon/pieces-framework';
+import { AppConnectionType } from '@agnocon/pieces-framework';
+import { JWT, OAuth2Client } from 'google-auth-library';
+
+export const googleDocsScopes = [
+	'https://www.googleapis.com/auth/documents',
+	'https://www.googleapis.com/auth/drive.readonly',
+	'https://www.googleapis.com/auth/drive',
+	'email',
+];
+
+export const googleDocsAuth = [PieceAuth.OAuth2({
+	description: '',
+	authUrl: 'https://accounts.google.com/o/oauth2/auth',
+	tokenUrl: 'https://oauth2.googleapis.com/token',
+	required: true,
+	scope: googleDocsScopes,
+}), PieceAuth.CustomAuth({
+	displayName: 'Service Account (Advanced)',
+	description: 'Authenticate via service account from https://console.cloud.google.com/ > IAM & Admin > Service Accounts > Create Service Account > Keys > Add key.  <br> <br> You can optionally use domain-wide delegation (https://support.google.com/a/answer/162106?hl=en#zippy=%2Cset-up-domain-wide-delegation-for-a-client) to access documents without adding the service account to each one. <br> <br> **Note:** Without a user email, the service account only has access to files/folders you explicitly share with it.',
+	required: true,
+	props: {
+		serviceAccount: Property.LongText({
+			displayName: 'Service Account JSON Key',
+			required: true,
+		}),
+		userEmail: Property.ShortText({
+			displayName: 'User Email',
+			required: false,
+			description: 'Email address of the user to impersonate for domain-wide delegation.',
+		}),
+	},
+	validate: async ({ auth }) => {
+		try {
+			await getAccessToken({
+				type: AppConnectionType.CUSTOM_AUTH,
+				props: { ...auth },
+			});
+		} catch (e) {
+			return {
+				valid: false,
+				error: (e as Error).message,
+			};
+		}
+		return {
+			valid: true,
+		};
+	},
+})];
+
+export type GoogleDocsAuthValue = AppConnectionValueForAuthProperty<typeof googleDocsAuth>;
+
+export async function createGoogleClient(auth: GoogleDocsAuthValue): Promise<OAuth2Client> {
+	if (auth.type === AppConnectionType.CUSTOM_AUTH) {
+		let serviceAccount;
+		try {
+			serviceAccount = JSON.parse(auth.props.serviceAccount);
+		} catch {
+			throw new Error('Invalid Service Account JSON Key. Please provide a valid JSON string.');
+		}
+		return new JWT({
+			email: serviceAccount.client_email,
+			key: serviceAccount.private_key,
+			scopes: googleDocsScopes,
+			subject: auth.props.userEmail,
+		});
+	}
+	const authClient = new OAuth2Client();
+	authClient.setCredentials(auth);
+	return authClient;
+}
+
+export const getAccessToken = async (auth: GoogleDocsAuthValue): Promise<string> => {
+	if (auth.type === AppConnectionType.CUSTOM_AUTH) {
+		const googleClient = await createGoogleClient(auth);
+		const response = await googleClient.getAccessToken();
+		if (response.token) {
+			return response.token;
+		} else {
+			throw new Error('Could not retrieve access token from service account json');
+		}
+	}
+	return auth.access_token;
+};

package/src/lib/common/index.ts

@@ -0,0 +1,126 @@
+/* eslint-disable @typescript-eslint/no-explicit-any */
+import { Property } from '@agnocon/pieces-framework';
+import { HttpMethod, httpClient, AuthenticationType } from '@agnocon/pieces-common';
+import { docs_v1 } from '@googleapis/docs';
+
+export const docsCommon = {
+	baseUrl: 'https://docs.googleapis.com/v1',
+	title: Property.ShortText({
+		displayName: 'Document Title',
+		required: true,
+	}),
+	body: Property.LongText({
+		displayName: 'Document Content',
+		required: true,
+	}),
+
+	// Creates an empty document with the title provided
+	createDocument: async (title: string, accessToken: string) => {
+		const createRequest = await httpClient.sendRequest({
+			url: `${docsCommon.baseUrl}/documents`,
+			method: HttpMethod.POST,
+			authentication: {
+				type: AuthenticationType.BEARER_TOKEN,
+				token: accessToken,
+			},
+			body: {
+				title: title,
+			},
+		});
+
+		return createRequest.body;
+	},
+
+	// Writes provided content to the end of an existing document
+	writeToDocument: async (documentId: string, body: string, accessToken: string) => {
+		const writeRequest = await httpClient.sendRequest({
+			url: `${docsCommon.baseUrl}/documents/${documentId}:batchUpdate`,
+			method: HttpMethod.POST,
+			authentication: {
+				type: AuthenticationType.BEARER_TOKEN,
+				token: accessToken,
+			},
+			body: {
+				requests: [
+					{
+						insertText: {
+							text: body,
+							endOfSegmentLocation: {},
+						},
+					},
+				],
+			},
+		});
+
+		return writeRequest.body;
+	},
+
+	// Converts block-level Markdown into Google Docs batchUpdate requests.
+	// Inserts each line left-to-right at a running cursor (starting at baseIndex)
+	// so every index references the document state after the prior inserts in the
+	// same batch (indices stay stable because each insert is at the prior insert's
+	// end). Block-level only: headings and bullets; inline marks are left as literal
+	// text. baseIndex defaults to 1 (start of body); pass a section start index to
+	// insert markdown into a freshly-emptied range mid-document.
+	markdownToBatchRequests: (markdown: string, baseIndex = 1): docs_v1.Schema$Request[] => {
+		const lines = markdown.replace(/\r\n/g, '\n').split('\n');
+		const requests: docs_v1.Schema$Request[] = [];
+		const bulletRanges: Array<{ startIndex: number; endIndex: number }> = [];
+		let cursor = baseIndex;
+
+		for (const line of lines) {
+			const headingMatch = /^(#{1,3})\s+(.*)$/.exec(line);
+			const bulletMatch = /^\s*[-*+]\s+(.*)$/.exec(line);
+
+			let textToInsert = line;
+			let headingLevel = 0;
+			let isBullet = false;
+			if (headingMatch) {
+				headingLevel = headingMatch[1].length;
+				textToInsert = headingMatch[2];
+			} else if (bulletMatch) {
+				isBullet = true;
+				textToInsert = bulletMatch[1];
+			}
+
+			requests.push({ insertText: { text: textToInsert + '\n', location: { index: cursor } } });
+			const paragraphStart = cursor;
+			const paragraphEnd = cursor + textToInsert.length + 1;
+
+			if (headingLevel > 0) {
+				requests.push({
+					updateParagraphStyle: {
+						range: { startIndex: paragraphStart, endIndex: paragraphEnd },
+						paragraphStyle: { namedStyleType: `HEADING_${headingLevel}` },
+						fields: 'namedStyleType',
+					},
+				});
+			}
+			if (isBullet) {
+				bulletRanges.push({ startIndex: paragraphStart, endIndex: paragraphEnd });
+			}
+
+			cursor = paragraphEnd;
+		}
+
+		for (const range of bulletRanges) {
+			requests.push({
+				createParagraphBullets: { range, bulletPreset: 'BULLET_DISC_CIRCLE_SQUARE' },
+			});
+		}
+
+		return requests;
+	},
+
+	// Maps a Google API (Gaxios) error to a concise, agent-readable message.
+	formatError: (error: any, action: string): string => {
+		const status = error?.response?.status ?? error?.code;
+		const apiMessage = error?.response?.data?.error?.message ?? error?.message;
+		const suffix = apiMessage ? ` ${apiMessage}` : '';
+		if (status === 400) return `Invalid request trying to ${action} the document (400) — often a bad index or range.${suffix}`;
+		if (status === 403) return `Permission denied trying to ${action} the document (403) — check the connection has access.${suffix}`;
+		if (status === 404) return `Document not found trying to ${action} (404) — verify the document ID.${suffix}`;
+		if (status === 429) return `Rate limit exceeded trying to ${action} the document (429) — retry later.${suffix}`;
+		return `Failed to ${action} the document${status ? ` (${status})` : ''}:${suffix || ' unknown error'}`;
+	},
+};

package/src/lib/common/props.ts

@@ -0,0 +1,55 @@
+import { googleDocsAuth, createGoogleClient, GoogleDocsAuthValue } from '../auth';
+import { DropdownOption, Property } from '@agnocon/pieces-framework';
+import { drive as googleDrive, drive_v3 } from '@googleapis/drive';
+
+export const folderIdProp = Property.Dropdown({
+	displayName: 'Folder',
+	refreshers: [],
+	auth: googleDocsAuth,
+	required: false,
+	options: async ({ auth }) => {
+		if (!auth) {
+			return {
+				disabled: true,
+				placeholder: 'Please connect to your Google Drive account.',
+				options: [],
+			};
+		}
+		const authValue = auth as GoogleDocsAuthValue;
+
+		const authClient = await createGoogleClient(authValue);
+
+		const drive = googleDrive({ version: 'v3', auth: authClient });
+
+		const options: DropdownOption<string>[] = [];
+
+		let nextPageToken;
+
+		do {
+			const response: any = await drive.files.list({
+				q: "mimeType='application/vnd.google-apps.folder' and trashed = false",
+				supportsAllDrives: true,
+                orderBy:'createdTime desc',
+				includeItemsFromAllDrives: true,
+				corpora: 'allDrives',
+				pageToken: nextPageToken,
+			});
+
+			const fileList: drive_v3.Schema$FileList = response.data;
+
+			if (fileList.files) {
+				for (const file of fileList.files)
+					options.push({
+						label: file.name!,
+						value: file.id!,
+					});
+			}
+			nextPageToken = response.data.nextPageToken;
+		} while (nextPageToken);
+
+		return {
+			disabled: false,
+			options,
+		};
+	},
+});