Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/TimRobinson1/notional
An unofficial Notion API for interacting with table data in NodeJS
https://github.com/TimRobinson1/notional
api-client api-wrapper javascript nodejs notion typescript
Last synced: 2 months ago
JSON representation
An unofficial Notion API for interacting with table data in NodeJS
- Host: GitHub
- URL: https://github.com/TimRobinson1/notional
- Owner: TimRobinson1
- Created: 2020-06-09T02:41:55.000Z (over 4 years ago)
- Default Branch: master
- Last Pushed: 2023-01-06T08:22:25.000Z (almost 2 years ago)
- Last Synced: 2024-06-12T15:08:58.184Z (5 months ago)
- Topics: api-client, api-wrapper, javascript, nodejs, notion, typescript
- Language: TypeScript
- Size: 403 KB
- Stars: 20
- Watchers: 3
- Forks: 1
- Open Issues: 13
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# Notional
> An unofficial Notion API for interacting with table data in NodeJS
_Notional: Existing as or based on a suggestion, estimate, or theory_ -- Cambridge Dictionary
---
## Basic Usage
Notional is still very much a work in progress, so please use with a degree of caution.
### Installation
```
npm i notional
yarn add notional
```
### Getting setup
To use `notional`, you'll need both an API key and your user ID. To acquire these, follow these steps:
- Using a browser (Google Chrome in this example), visit a Notion webpage and make sure you're logged in.
- Open your developer tools and navigate to the `Application` tab.
- Under `Storage`, click on `Cookies` and then click on cookies from `https://www.notion.so`.
- Here you should find a cookie called `token_v2`. This value is your `apiKey`.
- You should also see `notion_user_id`, which you will need as your `userId`.
### Tables
Let's say we have a table in Notion to keep track of our video games:
#### Reading from the table
Nice. Let's connect to that table in our code using `notional`, and read from our table all of the PC games that we have in our collection:
```javascript
import notional from 'notional';
// Let's just pretend that this is the URL of our table!
const TABLE_URL = 'https://www.notion.so/example/481ff7846d1a4f1c8f30e3a3911d9129';
const { table } = notional({
apiKey: process.env.NOTION_API_KEY,
userId: process.env.USER_ID,
});
async function readOutMyPCGames () {
const videoGamesTable = await table(TABLE_URL);
const pcGames = await videoGamesTable
.where({ Platform: 'PC' })
.get();
console.log(pcGames);
}
```
If we were to run that `readOutMyPCGames` function, we'd end up with an output like so:
```json
[
{
"Title": "Resident Evil 2",
"Platform": "PC",
"Genres": ["action", "horror", "shooter"],
"Finished": true,
"Date purchased": {
"type": "date",
"start_date": "2020-03-19"
}
},
{
"Title": "Fallout 4",
"Platform": "PC",
"Genres": ["action", "shooter"],
"Finished": false,
"Date purchased": {
"type": "date",
"start_date": "2019-10-22"
}
},
{
"Title": "Skyrim",
"Platform": "PC",
"Genres": ["adventure"],
"Finished": false,
"Date purchased": {
"type": "date",
"start_date": "2017-11-09"
}
}
]
```
#### Updating the table
I finished _Super Mario Odyssey_ recently, but it looks like the table is out of date and says I haven't finished it! Let's correct that.
We can set up the `videoGamesTable` variable in the same way as before, and then all we have to do:
```javascript
await videoGamesTable
.where({ Title: 'Super Mario Odyssey' })
.update({ Finished: true });
```
#### Inserting into the table
I've just bought the video game _Dark Souls_ this exact second, let's add that to our table!
```javascript
await videoGamesTable.insertRows([
{
"Title": "Dark Souls",
"Platform": "Xbox 360",
"Genres": ["action", "adventure"],
"Finished": false,
"Date purchased": (new Date()).toISOString(),
}
])
```
#### Deleting from the table
I don't think I'm going to be playing any more _Skyrim_ any time soon. In fact, let's just get rid of it and remove it from our table:
```javascript
await videoGamesTable
.where({ Title: 'Skyrim' })
.delete();
```
---