Notion Integration
Relevant source files
The following files were used as context for generating this wiki page:The Notion integration for Quix empowers the AI agent to connect with and interact with a user's Notion workspace directly from Slack. This allows users to search, browse, create, and update Notion pages, databases, and other content using natural language commands. The integration is designed as a modular package within the Quix architecture, providing a set of tools that the LLM can leverage to perform various actions on behalf of the user.
The core functionality includes managing pages, blocks, databases, comments, and users within Notion. Configuration is handled through a secure modal in the Slack App Home, where users provide an API token to establish the connection.
Sources: README.md:4-5, src/lib/constants.ts:160-172, agent-packages/packages/notion/src/tools.ts:21-34
Architecture and Core Components
The Notion integration is built around the NotionService class, which encapsulates all interactions with the Notion API. This service uses the official @notionhq/client library to make API calls.
Sources: agent-packages/packages/notion/src/index.ts:37-42
NotionService
The NotionService class is the central component of the integration. It is initialized with a NotionConfig object containing the necessary authentication token. It provides methods that correspond to the agent tools, such as retrievePage, queryDatabase, and appendBlockChildren. A key feature of this service is its robust error handling, which catches and standardizes errors from the Notion client.
Sources: agent-packages/packages/notion/src/index.ts:35-37
The diagram below illustrates the basic class structure.
Error Handling
The handleNotionError method within NotionService ensures that any issues during API communication are caught and formatted into a standardized BaseResponse object. It specifically handles different error types from the @notionhq/client, such as APIResponseError, RequestTimeoutError, and UnknownHTTPResponseError, providing detailed error information for debugging.
This diagram shows the error handling flow:
Configuration
To enable the Notion integration, a user must configure it through the Quix App Home in Slack. The configuration requires a Notion API token.
Sources: src/slack/views/modals.ts:370-422, src/lib/constants.ts:160-172
Configuration Parameters
The integration requires the following configuration details, which are stored securely.
| Parameter | Type | Description | Source File |
|---|---|---|---|
token | string | The API token for the Notion integration. Obtained from https://www.notion.so/my-integrations. | agent-packages/packages/notion/src/types.ts:5 |
workspace_name | string | The name of the connected Notion workspace. This is retrieved and displayed in the UI. | src/slack/views/app_home.ts:241-242 |
defaultPrompt | string | A default prompt used by the LLM when it needs to search, create, or update content in Notion. This is an optional configuration. | src/slack/views/modals.ts:405-418 |
Configuration Flow
The user initiates the configuration from the Slack App Home. This opens a modal where they can input their Notion API token.
The sequence diagram below shows the configuration process:
Agent Tools
The integration exposes a comprehensive set of tools to the LLM agent, allowing it to perform a wide range of actions in Notion. These tools are defined in createNotionToolsExport and are categorized by their operation type (Read, Create, Update, Delete).
Sources: agent-packages/packages/notion/src/tools.ts:46-210
| Tool Name | Operation | Description |
|---|---|---|
notion_retrieve_block | READ | Retrieve a block from Notion. |
notion_retrieve_block_children | READ | Retrieve the children of a block. |
notion_append_block_children | CREATE | Append new children blocks to a specified parent block. |
notion_delete_block | DELETE | Delete a block in Notion. |
notion_update_block | UPDATE | Update the content of a block based on its type. |
notion_retrieve_page | READ | Retrieve a page from Notion. |
notion_delete_or_archive_page | DELETE | Delete or archive a page in Notion. |
notion_update_page_properties | UPDATE | Update properties of a page or an item in a Notion database. |
notion_query_database | READ | Query a database in Notion. |
notion_create_database | CREATE | Create a new database in Notion. |
notion_retrieve_database | READ | Retrieve a database in Notion. |
notion_create_database_item | CREATE | Create a new item (page) in a Notion database. |
notion_create_comment | CREATE | Create a comment on a page or in a discussion. |
notion_retrieve_comments | READ | Retrieve a list of unresolved comments from a Notion page or block. |
notion_search | READ | Search pages or databases by title in Notion. |
notion_list_all_users | READ | List all users in the Notion workspace. |
notion_retrieve_user | READ | Retrieve a specific user by user_id. |
notion_retrieve_bot_user | READ | Retrieve the bot user associated with the current token. |
Sources: agent-packages/packages/notion/src/tools.ts:51-209
Data Schemas
The integration uses zod to define and validate the schemas for tool arguments and API payloads. These schemas ensure that the data passed to the NotionService and the Notion API is correctly structured.
Sources: agent-packages/packages/notion/src/schema.ts, agent-packages/packages/notion/src/types.ts
Key Schemas
-
richTextObjectSchema: A complex schema that defines the structure for rich text content in Notion, including text, mentions, equations, and various formatting annotations. It is a fundamental building block for most content-related operations.
Sources: agent-packages/packages/notion/src/schema.ts:6-338 -
blockObjectSchema: Defines the structure of a Notion block, such as a paragraph, heading, or list item. It usesrichTextObjectSchemafor its content and can contain nested child blocks.
Sources: agent-packages/packages/notion/src/schema.ts:340-361 -
queryDatabaseSchema: Defines the arguments for querying a Notion database, includingdatabase_id,filter,sorts, and pagination controls (start_cursor,page_size).
Sources: agent-packages/packages/notion/src/schema.ts:420-461 -
updatePagePropertiesSchema: Defines the arguments for updating properties of a page or a database item. It requires apage_idand apropertiesobject, where the keys correspond to the database's columns.
Sources: agent-packages/packages/notion/src/schema.ts:409-415 -
createDatabaseItemSchema: Defines the structure for creating a new item (page) within a database. It requires aparent(the database ID) and apropertiesobject containing the initial values for the new item's fields.
Sources: agent-packages/packages/notion/src/schema.ts:463-490
The diagram below shows the relationship between some of these key schemas.