Notion API client for dart.
See the ROADMAP file to see what is coming next.
API implemented
| Endpoint | Avaliable | Notes |
|---|---|---|
| Retrieve a database | |
|
| Query a database | |
Working on it |
| List databases | |
|
| Create a database | |
Workin on more properties |
| Retrieve a page | |
|
| Create a page | |
Workin on more properties |
| Update a page | |
Workin on more properties |
| Retrieve block children | |
|
| Append block children | |
|
| Retrieve a user | ||
| List all users | ||
| Search |
Usage
Important: The methods return a NotionResponse. You can find how to use it in its documentation.
NotionClient class
You only have to create a new instance of the NotionClient class and all the API requests will be available as class methods.
NotionClient notion = NotionClient(token: 'YOUR SECRET TOKEN FROM INTEGRATIONS PAGE');
Individual classes
You can also use individual request group class like NotionPagesClient or NotionDatabasesClient. They are used like the main client but the methods are class methods instead of class properties methods.
Example
// With main class
NotionClient notion = NotionClient(token: 'YOUR_TOKEN');
notion.databases.fetchAll();
// With individual class
NotionDatabasesClient databases = NotionDatabasesClient(token: 'YOUR_TOKEN');
databases.fetchAll();
A few examples
A page created and filled using only this package:
https://jonathangomz.notion.site/notion_api-example-0893dd2cb38a413d90165cb810b3c019
To see code to create the page above or see more examples go here.
Append blocks children
// Create children instance:
Children children = Children.withBlocks([
Heading(text: Text('Test')),
Paragraph(texts: [
Text('Lorem ipsum (A)'),
Text('Lorem ipsum (B)',
annotations: TextAnnotations(
bold: true,
underline: true,
color: ColorsTypes.Orange,
))
])
]);
// Send the instance to Notion
notion.blocks.append(
to: 'YOUR_BLOCK_ID',
children: children,
);
Create a page
// Create a page instance
Page page = Page(
parent: Parent.database(id: 'YOUR_DATABASE_ID'),
title: Text('NotionClient (v1): Page test'),
);
// Send the instance to Notion.
notion.pages.create(page);
Errors
Some errors that I have encounter and still don't know how to solve because are errors that also occur on Postman are:
Create page with chidren
When the parent is a page the error is:
"body failed validation: body.properties.title.type should be an array, instead was `\"array\"`."
But when the parent is a database then the error is:
"body failed validation: body.parent.page_id should be defined, instead was `undefined`."
You can create the page first and then add the children as shown in the examples.
Contributions
Please help, I don't even know if what I'm doing is right.
Rules
Some rules to follow:
- Please follow the dart convention format:
- If you are adding a new function, please also add the documentation.
- If you are adding a new parameters, please also add it to the current documentation.
- (Optional) Run the tests to know that everything is working just fine (See how run the tests).
- This is optional because sometimes the tests fail on GitHub actions so anyway I will check this on my computer.
Tests
To be able to run the tests you will have to have a .env file on the root directory with the next variables:
- TOKEN: The secret token.
- TEST_DATABASE_ID: The database id where you will be working on.
- TEST_PAGE_ID: Some page id inside the database specified above.
- TEST_BLOCK_ID: Some block id inside the page specified above.
- TEST_BLOCK_HEADING_ID: Some heading block id inside the page specified above.
Example:
The values are not valid of course.
TOKEN=secret_Oa24V8FbJ49JluJankVOQihyLiMXwqSQeeHuSFobQDW
TEST_DATABASE_ID=366da3d646bb458128071fdb2fbbf427
TEST_PAGE_ID=c3b53019-4470-443b-a141-95a3a1a44g60
TEST_BLOCK_ID=c8hac4bb32af48889228bf483d938e34
TEST_BLOCK_HEADING_ID=c8hac4bb32af48889228bf483d938e34
Next release
v1.2.1:
Release date: 02/Aug/2021
- Add constructors with only single text content with default style for:
Paragraph.text('some text here...')ToDo.text('some text here...', checked: true)Heading.text('some text here...', type: 2)BulletedListItem.text('some text here...')NumberedListItem.text('some text here...')Toggle.text('some text here...', children: [])
- Add more constructors for
Headingclass:one: Heading with type 1 by default.two: Heading with type 2 by default.three: Heading with type 3 by default.
- Add more constructors for
Textclass:code: Text with code style by default.italic: Text with italic style by default.bold: Text with bold style by default.- [Opt]
list: List of words separated by comma (by default).- Example:
Text.list()will receive a list of Text and will be concatenated separated with comma by default. It may be unnecessary. Can help to make the code more readable.
- Example:
- [Opt]
sep: Text separator.- Example:
Text.sep(), by default, will insert " " in a list ofTextinstances, but it will be able to do more things that I don't know yet, hehe. It may be unnecessary. Can help to make the code more readable.
- Example:
45 Sep 28, 2022
14 Oct 19, 2022
12 Jan 8, 2023
7 Dec 25, 2022
101 Dec 29, 2022
76 Dec 14, 2022
21 Dec 29, 2022
5 Nov 11, 2022
376 Dec 24, 2022
13 Dec 15, 2022
15 Oct 17, 2022
1.3k Dec 25, 2022
490 Jan 1, 2023
15 Dec 22, 2022
0 Nov 10, 2021
8 Nov 25, 2022
882 Dec 31, 2022
632 Dec 31, 2022
65 Oct 31, 2022