feat: add Google Sheets action

[nicosammito]

Summary

Add a Google Sheets action so flows can append, read, and update spreadsheet rows — the single most common "dump this somewhere I can see it" sink in automation, and a lightweight database for non-technical users. Consistently among the very top integrations on both n8n and Zapier.

n8n/Zapier validation: Google Sheets is a flagship node on n8n and one of the most-used apps on Zapier ("add row" / "lookup row" / "update row").

Suggested directory

actions/google-sheets-action

Triggers

The Sheets API has no push webhooks; triggers poll (values range diff or Drive changes feed), the same approach as the proposed Notion action.

• GoogleSheetsRowAdded — new row appended to a watched sheet (settings: spreadsheetId, sheetName)
• GoogleSheetsRowUpdated — a cell/row in a watched range changed (settings: spreadsheetId, range)

Functions

• sheetsAppendRow(spreadsheetId, sheetName, values): SHEETS_UPDATE_RESULT
• sheetsUpdateRange(spreadsheetId, range, values): SHEETS_UPDATE_RESULT
• sheetsGetRange(spreadsheetId, range): SHEETS_VALUE_RANGE
• sheetsLookupRow(spreadsheetId, sheetName, column, value): SHEETS_ROW
• sheetsClearRange(spreadsheetId, range): BOOLEAN
• sheetsCreateSheet(spreadsheetId, title): SHEETS_SHEET
• sheetsBatchUpdate(spreadsheetId, requests): SHEETS_BATCH_RESULT

Utils: sheetsCreateValueRange(...), sheetsCreateA1Range(...) (builders for the API's A1/value-range shapes, mirroring GLS create* utils).

Data types

One class per file in src/data_types/ (zod schema + @Identifier/@Name/@Schema):

• SheetsValueRange, SheetsUpdateResult, SheetsBatchResult, SheetsRow, SheetsSheet, SheetsSpreadsheetMeta

Auth / config via ConfigurationDefinition on the Action (like GLS client_id/client_secret) — service-account (JWT) auth, simplest for a headless action:

Identifier	Type	Description
service_account_json	TEXT	Service-account key JSON; grants access to sheets shared with its email
scopes	TEXT (optional)	OAuth scopes, default https://www.googleapis.com/auth/spreadsheets

Beyond the shared Hercules vars (HERCULES_AUTH_TOKEN, HERCULES_AQUILA_URL, HERCULES_ACTION_ID, HERCULES_SDK_VERSION) an action-specific GOOGLE_SERVICE_ACCOUNT_JSON (or GOOGLE_APPLICATION_CREDENTIALS path) may back the config default.

Rationale

Spreadsheet / lightweight-database domain, covered by nothing implemented (gls, shopify, shopware, twilio, woocommerce), in-development (stripe, github, twilio), or planned in open issues/PRs (S3, SFTP, MCP, Stripe, Discord, GitHub, SMTP, Cron, Rest, AI, WebSocket, MQTT). The S3/SFTP issues (#38/#37) are binary/file storage — this is structured tabular data with per-cell reads/writes, a different use case. A near-universal automation sink that complements every other action.