notion-ruby-client 0.0.8 → 1.0.0.pre.beta2
Sign up to get free protection for your applications and to get access to all the features.
- checksums.yaml +4 -4
- data/.devcontainer/Dockerfile +5 -0
- data/.devcontainer/boot.sh +1 -0
- data/.devcontainer/devcontainer.json +30 -0
- data/.github/workflows/ci.yml +1 -0
- data/.gitignore +7 -0
- data/.rubocop.yml +9 -0
- data/CHANGELOG.md +43 -0
- data/CONTRIBUTING.md +51 -0
- data/Gemfile.lock +38 -11
- data/README.md +354 -108
- data/bin/console +31 -0
- data/lib/notion/api/endpoints/blocks.rb +51 -7
- data/lib/notion/api/endpoints/databases.rb +60 -53
- data/lib/notion/api/endpoints/pages.rb +24 -7
- data/lib/notion/api/endpoints/search.rb +41 -0
- data/lib/notion/api/endpoints/users.rb +14 -3
- data/lib/notion/api/endpoints.rb +3 -1
- data/lib/notion/api/errors/too_many_requests.rb +15 -0
- data/lib/notion/api/errors.rb +0 -2
- data/lib/notion/config.rb +2 -0
- data/lib/notion/pagination/cursor.rb +5 -2
- data/lib/notion/version.rb +2 -2
- data/lib/notion-ruby-client.rb +2 -0
- data/notion-ruby-client.gemspec +5 -3
- data/spec/fixtures/notion/block.yml +146 -0
- data/spec/fixtures/notion/block_append_children.yml +76 -62
- data/spec/fixtures/notion/block_children.yml +80 -65
- data/spec/fixtures/notion/create_database.yml +67 -58
- data/spec/fixtures/notion/create_page.yml +68 -59
- data/spec/fixtures/notion/database.yml +78 -61
- data/spec/fixtures/notion/database_query.yml +81 -62
- data/spec/fixtures/notion/delete_block.yml +145 -0
- data/spec/fixtures/notion/page.yml +70 -57
- data/spec/fixtures/notion/page_property_item.yml +143 -0
- data/spec/fixtures/notion/paginated_block_children.yml +296 -242
- data/spec/fixtures/notion/paginated_database_query.yml +79 -62
- data/spec/fixtures/notion/paginated_databases_list.yml +78 -61
- data/spec/fixtures/notion/paginated_search.yml +301 -0
- data/spec/fixtures/notion/paginated_users_list.yml +143 -130
- data/spec/fixtures/notion/search.yml +160 -0
- data/spec/fixtures/notion/search_with_query.yml +152 -0
- data/spec/fixtures/notion/update_block.yml +148 -0
- data/spec/fixtures/notion/update_database.yml +152 -0
- data/spec/fixtures/notion/update_page.yml +71 -59
- data/spec/fixtures/notion/users.yml +69 -56
- data/spec/fixtures/notion/users_list.yml +143 -130
- data/spec/fixtures/notion/users_me.yml +144 -0
- data/spec/notion/api/endpoints/blocks_spec.rb +44 -12
- data/spec/notion/api/endpoints/databases_spec.rb +22 -27
- data/spec/notion/api/endpoints/pages_spec.rb +13 -16
- data/spec/notion/api/endpoints/search_spec.rb +26 -0
- data/spec/notion/api/endpoints/users_spec.rb +9 -4
- data/spec/notion/pagination/cursor_spec.rb +126 -0
- metadata +67 -15
- data/.rspec_status +0 -19
- data/notion-ruby-client-0.0.4.gem +0 -0
- data/scratchpad.rb +0 -22
- data/screenshots/create_notion_bot.png +0 -0
- data/spec/fixtures/notion/databases_list.yml +0 -133
data/README.md
CHANGED
@@ -1,5 +1,8 @@
|
|
1
1
|
# Notion Ruby Client
|
2
2
|
|
3
|
+
[![Gem Version](https://badge.fury.io/rb/notion-ruby-client.svg)](http://badge.fury.io/rb/notion-ruby-client)
|
4
|
+
[![CI workflow badge](https://github.com/orbit-love/notion-ruby-client/actions/workflows/ci.yml/badge.svg)](https://github.com/orbit-love/notion-ruby-client/actions/workflows/ci.yml)
|
5
|
+
|
3
6
|
A Ruby client for the Notion API.
|
4
7
|
|
5
8
|
## Table of Contents
|
@@ -7,8 +10,34 @@ A Ruby client for the Notion API.
|
|
7
10
|
- [Installation](#installation)
|
8
11
|
- [Usage](#usage)
|
9
12
|
- [Create a New Bot Integration](#create-a-new-bot-integration)
|
10
|
-
- [Declare the API
|
13
|
+
- [Declare the API token](#declare-the-api-token)
|
11
14
|
- [API Client](#api-client)
|
15
|
+
- [Instantiating a new Notion API client](#instantiating-a-new-notion-api-client)
|
16
|
+
- [Pagination](#pagination)
|
17
|
+
- [Endpoints](#endpoints)
|
18
|
+
- [Databases](#databases)
|
19
|
+
- [Query a database](#query-a-database)
|
20
|
+
- [Create a Database](#create-a-database)
|
21
|
+
- [Update a Database](#update-a-database)
|
22
|
+
- [Retrieve a database](#retrieve-a-database)
|
23
|
+
- [List databases](#list-databases)
|
24
|
+
- [Pages](#pages)
|
25
|
+
- [Retrieve a page](#retrieve-a-page)
|
26
|
+
- [Create a page](#create-a-page)
|
27
|
+
- [Update page](#update-page)
|
28
|
+
- [Retrieve a page property item](#retrieve-a-page-property-item)
|
29
|
+
- [Blocks](#blocks)
|
30
|
+
- [Retrieve a block](#retrieve-a-block)
|
31
|
+
- [Update a block](#update-a-block)
|
32
|
+
- [Delete a block](#delete-a-block)
|
33
|
+
- [Retrieve block children](#retrieve-block-children)
|
34
|
+
- [Append block children](#append-block-children)
|
35
|
+
- [Users](#users)
|
36
|
+
- [Retrieve your token's bot user](#retrieve-your-tokens-bot-user)
|
37
|
+
- [Retrieve a user](#retrieve-a-user)
|
38
|
+
- [List all users](#list-all-users)
|
39
|
+
- [Search](#search)
|
40
|
+
- [Acknowledgements](#acknowledgements)
|
12
41
|
|
13
42
|
## Installation
|
14
43
|
|
@@ -22,15 +51,15 @@ Run `bundle install`.
|
|
22
51
|
|
23
52
|
## Usage
|
24
53
|
|
25
|
-
### Create a New
|
54
|
+
### Create a New Integration
|
26
55
|
|
27
|
-
|
56
|
+
> :blue_book: **Before you start**
|
57
|
+
>
|
58
|
+
> Make sure you are an **Admin** user in your Notion workspace. If you're not an Admin in your current workspace, [create a new personal workspace for free](https://www.notion.so/notion/Create-join-switch-workspaces-3b9be78982a940a7a27ce712ca6bdcf5#9332861c775543d0965f918924448a6d).
|
28
59
|
|
29
|
-
1
|
30
|
-
2. Confirm that you are an Admin in the workspace (see Settings & Members > Members).
|
31
|
-
3. Go to Settings & Members, and click API
|
60
|
+
To create a new integration, follow the steps 1 & 2 outlined in the [Notion documentation](https://developers.notion.com/docs#getting-started). The “_Internal Integration Token_” is what is going to be used to authenticate API calls (referred to here as the “API token”).
|
32
61
|
|
33
|
-
|
62
|
+
> :blue_book: Integrations don't have access to any pages (or databases) in the workspace at first. **A user must share specific pages with an integration in order for those pages to be accessed using the API.**
|
34
63
|
|
35
64
|
### Declare the API token
|
36
65
|
|
@@ -56,119 +85,117 @@ You can specify the token or logger on a per-client basis:
|
|
56
85
|
client = Notion::Client.new(token: '<secret Notion API token>')
|
57
86
|
```
|
58
87
|
|
59
|
-
####
|
88
|
+
#### Pagination
|
60
89
|
|
61
|
-
|
90
|
+
The client natively supports [cursor pagination](https://developers.notion.com/reference/pagination) for methods that allow it, such as `users_list`. Supply a block and the client will make repeated requests adjusting the value of `start_cursor` with every response. The default page size is set to 100 (Notion’s current default and maximum) and can be adjusted via `Notion::Client.config.default_page_size` or by passing it directly into the API call.
|
62
91
|
|
63
92
|
```ruby
|
64
|
-
|
65
|
-
|
66
|
-
|
67
|
-
|
68
|
-
client.users_list do |page|
|
69
|
-
# paginate through all users
|
93
|
+
all_users = []
|
94
|
+
client.users_list(page_size: 25) do |page|
|
95
|
+
all_users.concat(page.results)
|
70
96
|
end
|
97
|
+
all_users # All users, retrieved 25 at a time
|
71
98
|
```
|
72
99
|
|
73
|
-
|
100
|
+
When using cursor pagination the client will automatically pause and then retry the request if it runs into [Notion rate limiting](https://developers.notion.com/reference/errors#request-limits). (It will pause for 10 seconds before retrying the request, a value that can be overriden with `Notion::Client.config.default_retry_after`.) If it receives too many rate-limited responses in a row it will give up and raise an error. The default number of retries is 100 and can be adjusted via `Notion::Client.config.default_max_retries` or by passing it directly into the method as `max_retries`.
|
101
|
+
|
102
|
+
You can also proactively avoid rate limiting by adding a pause between every paginated request with the `sleep_interval` parameter, which is given in seconds.
|
74
103
|
|
75
104
|
```ruby
|
76
|
-
|
105
|
+
all_users = []
|
106
|
+
client.users_list(sleep_interval: 5, max_retries: 20) do |page|
|
107
|
+
# pauses for 5 seconds between each request
|
108
|
+
# gives up after 20 consecutive rate-limited responses
|
109
|
+
all_users.concat(page.results)
|
110
|
+
end
|
111
|
+
all_users
|
77
112
|
```
|
78
113
|
|
79
|
-
|
114
|
+
## Endpoints
|
115
|
+
|
116
|
+
### Databases
|
80
117
|
|
81
|
-
|
118
|
+
#### Query a database
|
119
|
+
|
120
|
+
Gets a paginated array of [Page](https://developers.notion.com/reference/page) objects contained in the database, filtered and ordered according to the filter conditions and sort criteria provided in the request.
|
82
121
|
|
83
122
|
```ruby
|
84
|
-
client.database_query(
|
123
|
+
client.database_query(database_id: 'e383bcee-e0d8-4564-9c63-900d307abdb0') # retrieves the first page
|
85
124
|
|
86
|
-
client.database_query(
|
125
|
+
client.database_query(database_id: 'e383bcee-e0d8-4564-9c63-900d307abdb0', start_cursor: 'fe2cc560-036c-44cd-90e8-294d5a74cebc')
|
87
126
|
|
88
|
-
client.database_query(
|
127
|
+
client.database_query(database_id: 'e383bcee-e0d8-4564-9c63-900d307abdb0') do |page|
|
89
128
|
# paginate through all pages
|
90
129
|
end
|
91
130
|
|
92
131
|
# Filter and sort the database
|
93
132
|
sort = [
|
94
133
|
{
|
95
|
-
|
96
|
-
|
134
|
+
'property': 'Last ordered',
|
135
|
+
'direction': 'ascending'
|
97
136
|
}
|
98
137
|
]
|
99
138
|
filter = {
|
100
|
-
|
139
|
+
'or': [
|
101
140
|
{
|
102
|
-
|
103
|
-
|
104
|
-
|
141
|
+
'property': 'In stock',
|
142
|
+
'checkbox': {
|
143
|
+
'equals': true
|
105
144
|
}
|
106
145
|
},
|
107
146
|
{
|
108
|
-
|
109
|
-
|
110
|
-
|
147
|
+
'property': 'Cost of next trip',
|
148
|
+
'number': {
|
149
|
+
'greater_than_or_equal_to': 2
|
111
150
|
}
|
112
151
|
}
|
113
152
|
]
|
114
153
|
}
|
115
|
-
client.database_query(
|
116
|
-
```
|
117
|
-
|
118
|
-
Get a single Database:
|
119
|
-
|
120
|
-
```ruby
|
121
|
-
client.database(id: 'e383bcee-e0d8-4564-9c63-900d307abdb0')
|
154
|
+
client.database_query(database_id: 'e383bcee-e0d8-4564-9c63-900d307abdb0', sort: sort, filter: filter)
|
122
155
|
```
|
123
156
|
|
124
|
-
|
157
|
+
See [Pagination](#pagination) for details about how to iterate through the list.
|
125
158
|
|
126
|
-
|
127
|
-
client.databases_list # retrieves the first page
|
128
|
-
|
129
|
-
client.databases_list(start_cursor: 'fe2cc560-036c-44cd-90e8-294d5a74cebc')
|
159
|
+
See the full endpoint documentation on [Notion Developers](https://developers.notion.com/reference/post-database-query).
|
130
160
|
|
131
|
-
|
132
|
-
# paginate through all databases
|
133
|
-
end
|
134
|
-
```
|
161
|
+
#### Create a Database
|
135
162
|
|
136
|
-
|
163
|
+
Creates a database as a subpage in the specified parent page, with the specified properties schema.
|
137
164
|
|
138
165
|
```ruby
|
139
166
|
title = [
|
140
167
|
{
|
141
|
-
|
142
|
-
|
143
|
-
|
144
|
-
|
168
|
+
'type': 'text',
|
169
|
+
'text': {
|
170
|
+
'content': 'Grocery List',
|
171
|
+
'link': nil
|
145
172
|
}
|
146
173
|
}
|
147
|
-
]
|
174
|
+
]
|
148
175
|
properties = {
|
149
|
-
|
150
|
-
|
176
|
+
'Name': {
|
177
|
+
'title': {}
|
151
178
|
},
|
152
|
-
|
153
|
-
|
179
|
+
'Description': {
|
180
|
+
'rich_text': {}
|
154
181
|
},
|
155
|
-
|
156
|
-
|
182
|
+
'In stock': {
|
183
|
+
'checkbox': {}
|
157
184
|
},
|
158
|
-
|
159
|
-
|
160
|
-
|
185
|
+
'Food group': {
|
186
|
+
'select': {
|
187
|
+
'options': [
|
161
188
|
{
|
162
|
-
|
163
|
-
|
189
|
+
'name': '🥦Vegetable',
|
190
|
+
'color': 'green'
|
164
191
|
},
|
165
192
|
{
|
166
|
-
|
167
|
-
|
193
|
+
'name': '🍎Fruit',
|
194
|
+
'color': 'red'
|
168
195
|
},
|
169
196
|
{
|
170
|
-
|
171
|
-
|
197
|
+
'name': '💪Protein',
|
198
|
+
'color': 'yellow'
|
172
199
|
}
|
173
200
|
]
|
174
201
|
}
|
@@ -181,53 +208,127 @@ client.create_database(
|
|
181
208
|
)
|
182
209
|
```
|
183
210
|
|
184
|
-
|
211
|
+
See the full endpoint documentation on [Notion Developers](https://developers.notion.com/reference/create-a-database).
|
185
212
|
|
186
|
-
|
213
|
+
#### Update a Database
|
214
|
+
|
215
|
+
Updates an existing database as specified by the parameters.
|
216
|
+
|
217
|
+
```ruby
|
218
|
+
title = [
|
219
|
+
{
|
220
|
+
'text': {
|
221
|
+
'content': 'Orbit 💜 Notion'
|
222
|
+
}
|
223
|
+
}
|
224
|
+
]
|
225
|
+
client.update_database(database_id: 'dd428e9dd3fe4171870da7a1902c748b', title: title)
|
226
|
+
```
|
227
|
+
|
228
|
+
See the full endpoint documentation on [Notion Developers](https://developers.notion.com/reference/update-a-database).
|
229
|
+
|
230
|
+
#### Retrieve a database
|
231
|
+
|
232
|
+
Retrieves a [Database object](https://developers.notion.com/reference-link/database) using the ID specified.
|
233
|
+
|
234
|
+
```ruby
|
235
|
+
client.database(database_id: 'e383bcee-e0d8-4564-9c63-900d307abdb0')
|
236
|
+
```
|
237
|
+
|
238
|
+
See the full endpoint documentation on [Notion Developers](https://developers.notion.com/reference/retrieve-a-database).
|
239
|
+
|
240
|
+
#### List databases
|
241
|
+
|
242
|
+
List all [Databases](https://developers.notion.com/reference-link/database) shared with the authenticated integration.
|
243
|
+
|
244
|
+
```ruby
|
245
|
+
client.databases_list # retrieves the first page
|
246
|
+
|
247
|
+
client.databases_list(start_cursor: 'fe2cc560-036c-44cd-90e8-294d5a74cebc')
|
248
|
+
|
249
|
+
client.databases_list do |page|
|
250
|
+
# paginate through all databases
|
251
|
+
end
|
252
|
+
```
|
253
|
+
|
254
|
+
See [Pagination](#pagination) for details about how to iterate through the list.
|
255
|
+
|
256
|
+
See the full endpoint documentation on [Notion Developers](https://developers.notion.com/reference/list-databases).
|
257
|
+
|
258
|
+
### Pages
|
259
|
+
|
260
|
+
#### Retrieve a page
|
261
|
+
|
262
|
+
Retrieves a [Page object](https://developers.notion.com/reference-link/page) using the ID specified.
|
263
|
+
|
264
|
+
> :blue_book: Responses contains page **properties**, not page content. To fetch page content, use the [retrieve block children](#retrieve-block-children) endpoint.
|
265
|
+
|
266
|
+
```ruby
|
267
|
+
client.page(page_id: 'b55c9c91-384d-452b-81db-d1ef79372b75')
|
268
|
+
```
|
269
|
+
|
270
|
+
See the full endpoint documentation on [Notion Developers](https://developers.notion.com/reference/retrieve-a-page).
|
271
|
+
|
272
|
+
#### Create a page
|
273
|
+
|
274
|
+
Creates a new page in the specified database or as a child of an existing page.
|
275
|
+
|
276
|
+
If the parent is a database, the [property values](https://developers.notion.com/reference-link/page-property-value) of the new page in the properties parameter must conform to the parent [database](https://developers.notion.com/reference-link/database)'s property schema.
|
277
|
+
|
278
|
+
If the parent is a page, the only valid property is `title`.
|
279
|
+
|
280
|
+
The new page may include page content, described as [blocks](https://developers.notion.com/reference-link/block) in the children parameter.
|
187
281
|
|
188
282
|
```ruby
|
189
283
|
properties = {
|
190
|
-
|
191
|
-
|
284
|
+
'Name': {
|
285
|
+
'title': [
|
192
286
|
{
|
193
|
-
|
194
|
-
|
287
|
+
'text': {
|
288
|
+
'content': 'Tuscan Kale'
|
195
289
|
}
|
196
290
|
}
|
197
291
|
]
|
198
292
|
},
|
199
|
-
|
200
|
-
|
293
|
+
'Description': {
|
294
|
+
'rich_text': [
|
201
295
|
{
|
202
|
-
|
203
|
-
|
296
|
+
'text': {
|
297
|
+
'content': 'A dark green leafy vegetable'
|
204
298
|
}
|
205
299
|
}
|
206
300
|
]
|
207
301
|
},
|
208
|
-
|
209
|
-
|
302
|
+
'Food group': {
|
303
|
+
'select': {
|
304
|
+
'name': '🥦 Vegetable'
|
305
|
+
}
|
210
306
|
},
|
211
|
-
|
307
|
+
'Price': {
|
308
|
+
'number': 2.5
|
309
|
+
}
|
212
310
|
}
|
213
311
|
children = [
|
214
312
|
{
|
215
|
-
|
216
|
-
|
217
|
-
|
218
|
-
|
313
|
+
'object': 'block',
|
314
|
+
'type': 'heading_2',
|
315
|
+
'heading_2': {
|
316
|
+
'rich_text': [{
|
317
|
+
'type": 'text',
|
318
|
+
'text': { 'content': 'Lacinato kale' }
|
319
|
+
}]
|
219
320
|
}
|
220
321
|
},
|
221
322
|
{
|
222
|
-
|
223
|
-
|
224
|
-
|
225
|
-
|
323
|
+
'object': 'block',
|
324
|
+
'type": 'paragraph',
|
325
|
+
'paragraph': {
|
326
|
+
'rich_text': [
|
226
327
|
{
|
227
|
-
|
228
|
-
|
229
|
-
|
230
|
-
|
328
|
+
'type': 'text',
|
329
|
+
'text': {
|
330
|
+
'content': 'Lacinato kale is a variety of kale with a long tradition in Italian cuisine, especially that of Tuscany. It is also known as Tuscan kale, Italian kale, dinosaur kale, kale, flat back kale, palm tree kale, or black Tuscan palm.',
|
331
|
+
'link': { 'url': 'https://en.wikipedia.org/wiki/Lacinato_kale' }
|
231
332
|
}
|
232
333
|
}
|
233
334
|
]
|
@@ -241,46 +342,191 @@ client.create_page(
|
|
241
342
|
)
|
242
343
|
```
|
243
344
|
|
244
|
-
|
345
|
+
See the full endpoint documentation on [Notion Developers](https://developers.notion.com/reference/post-page).
|
346
|
+
|
347
|
+
#### Update page
|
348
|
+
|
349
|
+
Updates [page property values](https://developers.notion.com/reference-link/page-property-value) for the specified page. Properties that are not set via the `properties` parameter will remain unchanged.
|
350
|
+
|
351
|
+
If the parent is a database, the new [property values](https://developers.notion.com/reference-link/page-property-value) in the `properties` parameter must conform to the parent [database](https://developers.notion.com/reference-link/database)'s property schema.
|
352
|
+
|
353
|
+
```ruby
|
354
|
+
properties = {
|
355
|
+
'In stock': {
|
356
|
+
'checkbox': true
|
357
|
+
}
|
358
|
+
}
|
359
|
+
client.update_page(page_id: 'b55c9c91-384d-452b-81db-d1ef79372b75', properties: properties)
|
360
|
+
```
|
361
|
+
|
362
|
+
See the full endpoint documentation on [Notion Developers](https://developers.notion.com/reference/patch-page).
|
363
|
+
|
364
|
+
#### Retrieve a page property item
|
365
|
+
|
366
|
+
Retrieves a `property_item` object for a given `page_id` and `property_id`. Depending on the property type, the object returned will either be a value or a [paginated](#pagination) list of property item values. See [Property item objects](https://developers.notion.com/reference/property-item-object) for specifics.
|
367
|
+
|
368
|
+
To obtain `property_id`'s, use the [Retrieve a database endpoint](#retrieve-a-database).
|
369
|
+
|
370
|
+
```ruby
|
371
|
+
client.page_property_item(
|
372
|
+
page_id: 'b55c9c91-384d-452b-81db-d1ef79372b75',
|
373
|
+
property_id: 'aBcD123'
|
374
|
+
)
|
375
|
+
```
|
376
|
+
|
377
|
+
See the full endpoint documentation on [Notion Developers](https://developers.notion.com/reference/retrieve-a-page-property).
|
378
|
+
|
379
|
+
### Blocks
|
380
|
+
|
381
|
+
#### Retrieve a block
|
382
|
+
|
383
|
+
Retrieves a [Block object](https://developers.notion.com/reference-link/block) using the ID specified.
|
384
|
+
|
385
|
+
> :blue_book: If a block contains the key `has_children: true`, use the [Retrieve block children](#retrieve-block-children) endpoint to get the list of children
|
245
386
|
|
246
387
|
```ruby
|
247
|
-
client.
|
388
|
+
client.block(block_id: '9bc30ad4-9373-46a5-84ab-0a7845ee52e6')
|
248
389
|
```
|
249
390
|
|
250
|
-
|
391
|
+
See the full endpoint documentation on [Notion Developers](https://developers.notion.com/reference/retrieve-a-block).
|
392
|
+
|
393
|
+
#### Update a block
|
394
|
+
|
395
|
+
Updates the content for the specified block_id based on the block type. Supported fields based on the block object type (see [Block object](https://developers.notion.com/reference-link/block#block-type-object) for available fields and the expected input for each field).
|
396
|
+
|
397
|
+
**Note** The update replaces the entire value for a given field. If a field is omitted (ex: omitting checked when updating a to_do block), the value will not be changed.
|
251
398
|
|
252
399
|
```ruby
|
253
|
-
|
254
|
-
|
400
|
+
to_do = {
|
401
|
+
'rich_text': [{
|
402
|
+
'type': 'text',
|
403
|
+
'text': { 'content': 'Lacinato kale' }
|
404
|
+
}],
|
405
|
+
'checked': false
|
255
406
|
}
|
256
|
-
client.
|
407
|
+
client.update_block(block_id: '9bc30ad4-9373-46a5-84ab-0a7845ee52e6', 'to_do' => to_do)
|
408
|
+
```
|
409
|
+
|
410
|
+
See the full endpoint documentation on [Notion Developers](https://developers.notion.com/reference/retrieve-a-block).
|
411
|
+
|
412
|
+
#### Delete a block
|
413
|
+
|
414
|
+
Sets a [Block object](https://developers.notion.com/reference/block), including page blocks, to archived: true using the ID specified. Note: in the Notion UI application, this moves the block to the "Trash" where it can still be accessed and restored.
|
415
|
+
|
416
|
+
To restore the block with the API, use the [Update a block](#update-a-block) or [Update page](#update-page) respectively.
|
417
|
+
|
418
|
+
```ruby
|
419
|
+
client.delete_block(block_id: '9bc30ad4-9373-46a5-84ab-0a7845ee52e6')
|
257
420
|
```
|
258
421
|
|
259
|
-
|
422
|
+
See the full endpoint documentation on [Notion Developers](https://developers.notion.com/reference/delete-a-block).
|
260
423
|
|
261
|
-
Retrieve children
|
424
|
+
#### Retrieve block children
|
425
|
+
|
426
|
+
Returns a paginated array of child [block objects](https://developers.notion.com/reference-link/block) contained in the block using the ID specified. In order to receive a complete representation of a block, you may need to recursively retrieve the block children of child blocks.
|
262
427
|
|
263
428
|
```ruby
|
264
|
-
client.block_children(
|
429
|
+
client.block_children(block_id: 'b55c9c91-384d-452b-81db-d1ef79372b75')
|
265
430
|
|
266
|
-
client.block_children(start_cursor: 'fe2cc560-036c-44cd-90e8-294d5a74cebc')
|
431
|
+
client.block_children(block_id: 'b55c9c91-384d-452b-81db-d1ef79372b75', start_cursor: 'fe2cc560-036c-44cd-90e8-294d5a74cebc')
|
267
432
|
|
268
|
-
client.
|
433
|
+
client.block_children(block_id: 'b55c9c91-384d-452b-81db-d1ef79372b75') do |page|
|
269
434
|
# paginate through all children
|
270
435
|
end
|
271
436
|
```
|
272
437
|
|
273
|
-
|
438
|
+
See [Pagination](#pagination) for details about how to iterate through the list.
|
439
|
+
|
440
|
+
See the full endpoint documentation on [Notion Developers](https://developers.notion.com/reference/get-block-children).
|
441
|
+
|
442
|
+
#### Append block children
|
443
|
+
|
444
|
+
Creates and appends new children blocks to the parent block specified by `block_id`.
|
445
|
+
|
446
|
+
Returns a paginated list of newly created first level children block objects.
|
274
447
|
|
275
448
|
```ruby
|
276
449
|
children = [
|
277
450
|
{
|
278
451
|
"object": 'block',
|
279
452
|
"type": 'heading_2',
|
280
|
-
|
281
|
-
|
453
|
+
'heading_2': {
|
454
|
+
'rich_text': [{
|
455
|
+
'type': 'text',
|
456
|
+
'text': { 'content': 'A Second-level Heading' }
|
457
|
+
}]
|
282
458
|
}
|
283
459
|
}
|
284
460
|
]
|
285
|
-
client.block_append_children(
|
461
|
+
client.block_append_children(block_id: 'b55c9c91-384d-452b-81db-d1ef79372b75', children: children)
|
286
462
|
```
|
463
|
+
|
464
|
+
See the full endpoint documentation on [Notion Developers](https://developers.notion.com/reference/patch-block-children).
|
465
|
+
|
466
|
+
### Users
|
467
|
+
|
468
|
+
#### Retrieve your token's bot user
|
469
|
+
|
470
|
+
Retrieves the bot [User](https://developers.notion.com/reference/user) associated with the API token provided in the authorization header. The bot will have an `owner` field with information about the person who authorized the integration.
|
471
|
+
|
472
|
+
```ruby
|
473
|
+
client.me
|
474
|
+
```
|
475
|
+
|
476
|
+
See the full endpoint documentation on [Notion Developers](https://developers.notion.com/reference/get-self).
|
477
|
+
|
478
|
+
#### Retrieve a user
|
479
|
+
|
480
|
+
Retrieves a [User](https://developers.notion.com/reference/user) using the ID specified.
|
481
|
+
|
482
|
+
```ruby
|
483
|
+
client.user(user_id: 'd40e767c-d7af-4b18-a86d-55c61f1e39a4')
|
484
|
+
```
|
485
|
+
|
486
|
+
See the full endpoint documentation on [Notion Developers](https://developers.notion.com/reference/get-user).
|
487
|
+
|
488
|
+
#### List all users
|
489
|
+
|
490
|
+
Returns a paginated list of [Users](https://developers.notion.com/reference/user) for the workspace.
|
491
|
+
|
492
|
+
```ruby
|
493
|
+
client.users_list # retrieves the first page
|
494
|
+
|
495
|
+
client.users_list(start_cursor: 'fe2cc560-036c-44cd-90e8-294d5a74cebc')
|
496
|
+
|
497
|
+
client.users_list do |page|
|
498
|
+
# paginate through all users
|
499
|
+
end
|
500
|
+
```
|
501
|
+
|
502
|
+
See [Pagination](#pagination) for details about how to iterate through the list.
|
503
|
+
|
504
|
+
See the full endpoint documentation on [Notion Developers](https://developers.notion.com/reference/get-users).
|
505
|
+
|
506
|
+
### Search
|
507
|
+
|
508
|
+
Searches all pages and child pages that are shared with the integration. The results may include databases.
|
509
|
+
|
510
|
+
```ruby
|
511
|
+
client.search # search through every available page and database
|
512
|
+
|
513
|
+
client.search(query: 'Specific query') # limits which pages are returned by comparing the query to the page title
|
514
|
+
|
515
|
+
client.search(filter: { property: 'object', value: 'page' }) # only returns pages
|
516
|
+
|
517
|
+
client.search(sort: { direction: 'ascending', timestamp: 'last_edited_time' }) # sorts the results based on the provided criteria.
|
518
|
+
|
519
|
+
client.search(start_cursor: 'fe2cc560-036c-44cd-90e8-294d5a74cebc')
|
520
|
+
|
521
|
+
client.search do |page|
|
522
|
+
# paginate through all search pages
|
523
|
+
end
|
524
|
+
```
|
525
|
+
|
526
|
+
See [Pagination](#pagination) for details about how to iterate through the list.
|
527
|
+
|
528
|
+
See the full endpoint documentation on [Notion Developers](https://developers.notion.com/reference/post-search).
|
529
|
+
|
530
|
+
## Acknowledgements
|
531
|
+
|
532
|
+
The code, specs and documentation of this gem are an adaptation of the fantastic [Slack Ruby Client](https://github.com/slack-ruby/slack-ruby-client) gem. Many thanks to its author and maintainer [@dblock](https://github.com/dblock) and [contributors](https://github.com/slack-ruby/slack-ruby-client/graphs/contributors).
|
data/bin/console
ADDED
@@ -0,0 +1,31 @@
|
|
1
|
+
#!/usr/bin/env ruby
|
2
|
+
# frozen_string_literal: true
|
3
|
+
|
4
|
+
require "bundler/setup"
|
5
|
+
require "dotenv/load"
|
6
|
+
require "notion-ruby-client"
|
7
|
+
|
8
|
+
# You can add fixtures and/or initialization code here to make experimenting
|
9
|
+
# with your gem easier. You can also use a different console, if you like.
|
10
|
+
|
11
|
+
# (If you use this, don't forget to add pry to your Gemfile!)
|
12
|
+
# require "pry"
|
13
|
+
# Pry.start
|
14
|
+
|
15
|
+
require "irb"
|
16
|
+
|
17
|
+
def reload!(print = true)
|
18
|
+
puts 'Reloading ...' if print
|
19
|
+
# Main project directory.
|
20
|
+
root_dir = File.expand_path('..', __dir__)
|
21
|
+
# Directories within the project that should be reloaded.
|
22
|
+
reload_dirs = %w{lib}
|
23
|
+
# Loop through and reload every file in all relevant project directories.
|
24
|
+
reload_dirs.each do |dir|
|
25
|
+
Dir.glob("#{root_dir}/#{dir}/**/*.rb").each { |f| load(f) }
|
26
|
+
end
|
27
|
+
# Return true when complete.
|
28
|
+
true
|
29
|
+
end
|
30
|
+
|
31
|
+
IRB.start(__FILE__)
|