feat: add Notion action

[nicosammito]

Summary

Add a Notion action so flows can read and write Notion databases and pages — turning Notion into a lightweight backing store, task tracker, or knowledge base for automations. Notion is a top productivity integration on both n8n and Zapier.

n8n/Zapier validation: dedicated Notion node on n8n; one of the most popular productivity apps on Zapier for "create database item / update page" automations.

Suggested directory

actions/notion-action

Triggers

Notion has no native push webhooks for most events, so triggers use polling against the API (search/database-query with a cursor on last_edited_time). Where the codebase lacks a polling base, this can piggyback on a scheduled/cron-style event or a lightweight interval poller in the action process.

• NotionDatabaseItemCreated — new page in a watched database (setting: databaseId)
• NotionDatabaseItemUpdated — page in a watched database edited (setting: databaseId)
• NotionPagePropertyChanged — a watched property changed (settings: databaseId, propertyName)

Functions

• notionCreatePage(parentDatabaseId, properties, children?): NOTION_PAGE
• notionUpdatePage(pageId, properties): NOTION_PAGE
• notionGetPage(pageId): NOTION_PAGE
• notionArchivePage(pageId): BOOLEAN
• notionQueryDatabase(databaseId, filter?, sorts?): NOTION_QUERY_RESULT
• notionAppendBlocks(pageId, children): NOTION_BLOCK_LIST
• notionSearch(query, filter?): NOTION_SEARCH_RESULT

Utils: notionCreateRichText(...), notionCreatePropertyValue(...) (builders for Notion's nested property/rich-text shapes, mirroring GLS create* utils).

Data types

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

• NotionPage, NotionDatabase, NotionBlock, NotionBlockList, NotionQueryResult, NotionSearchResult, NotionRichText, NotionPropertyValue, NotionUser

Auth / config via ConfigurationDefinition on the Action (like GLS client_id/client_secret):

Identifier	Type	Description
integration_token	TEXT	Internal-integration token (Bearer) for the Notion API
notion_version	TEXT (optional)	Notion-Version header, default a pinned date e.g. 2022-06-28

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

Rationale

Productivity / document-database domain, untouched by any implemented action (gls, shopify, shopware, twilio, woocommerce), in-development branch (stripe, github, twilio), or open issue/PR (S3, SFTP, MCP, Stripe, Discord, GitHub, SMTP, Cron, Rest, AI, WebSocket, MQTT). Distinct from the planned MCP (#40) and AI (#2) actions: this is direct Notion CRUD, not model/tool plumbing. Gives flows a human-readable store to log or drive work items.