notion-ruby-client 0.0.8 → 0.1.0.pre.beta1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 819fe0911c48a9f09bb4a8e7c92b1c36f77fc61878944df6da74bfab0bd3a9cf
-  data.tar.gz: 2c93279f5b48004a93b92e0a1268712472ac7e5534dcb57ab8003dd8507676ef
+  metadata.gz: a9b83ad4b81b6b52c55b8b65bf33f3075733116d91470d237d000a2428f933ea
+  data.tar.gz: f77c9065b91514bfd3acb7ab42c8a8916c022f6725918861ab5ffce47dedd2df
 SHA512:
-  metadata.gz: 8d4a7d57457cdbb614eb9600b14e5f4460d0672631ff10f2525b87783f587ed251e4b3e3fc33d04420fe06cd086536b17acbfe008595a2f404cb513887365bdc
-  data.tar.gz: ffdab9a3e8962cfd8f21fd75a274020eba721963d12b7cfbb010eff711e7b7ef7945b2763a8db6f75130f53dc2408e7eafb3f95b9d0e3281cbb2b041cfd57e19
+  metadata.gz: b080379a4840e4b925a6b7bcb5e4c5ea7a25a85856947281cc95eddcc718dd16bb14466d127fca2d2b02a028e4f5df62ea3225ac1a614057578144e43220288c
+  data.tar.gz: aebf1260e3c10c54abebf62259beb35ab0d4ad520c8f26de98a163ed26d5e1989b09ef3d2189622a0a9b34552ac0b0d0085c567d3cd3488fc4a788fd0ba082a9

data/.github/workflows/ci.yml

@@ -1,4 +1,5 @@
 on: [push, pull_request]
+name: Continuous Integration
 jobs:
   test:
     strategy:

data/.gitignore

@@ -0,0 +1,7 @@
+.env
+pkg
+Gemfile.lock
+.DS_Store
+.bundle
+.idea
+.rspec_status

data/.rubocop.yml

@@ -35,6 +35,15 @@ RSpec/ExampleLength:
 RSpec/MultipleExpectations:
   Enabled: false
 
+RSpec/FilePath:
+  Enabled: false
+
+RSpec/MessageSpies:
+  Enabled: false
+
+RSpec/NestedGroups:
+  Max: 5
+
 Style/Documentation:
   Enabled: false
 

data/CHANGELOG.md

@@ -1,3 +1,22 @@
+### 0.1.0-beta1 (2021-08-29)
+
+#### New
+
+- Add support for the following new endpoints:
+  - [Update database](https://developers.notion.com/reference/update-a-database)
+  - [Update page](https://developers.notion.com/reference/patch-page)
+  - [Retrieve a block](https://developers.notion.com/reference/retrieve-a-block)
+  - [Update a block](https://developers.notion.com/reference/update-a-block)
+  - [Search](https://developers.notion.com/reference/search)
+- Update Notion API Version to `2021-08-16`
+- Add `bin/console` command for better DX
+- Overhauled documentation
+
+#### Upgrade instructions
+
+- Please refer to the Notion Changelog to see breaking changes for version `2021-08-16`
+- Regarding this gem, a lot of `id` parameters got renamed to `block_id`, `page_id`, `user_id` and `database_id`. You might need to rename those in your code as well.
+
 ### 0.0.8 (2021-07-27)
 
 - Bump `Notion-Version` header to `2021-05-13` (@H0R15H0)

data/Gemfile.lock

@@ -1,7 +1,9 @@
 PATH
   remote: .
   specs:
-    notion-ruby-client (0.0.8)
+    notion-ruby-client (0.1.0.pre.beta1)
+      activesupport
+      dotenv
       faraday (>= 1.0)
       faraday_middleware
       hashie
@@ -9,37 +11,54 @@ PATH
 GEM
   remote: http://rubygems.org/
   specs:
+    activesupport (6.1.4.1)
+      concurrent-ruby (~> 1.0, >= 1.0.2)
+      i18n (>= 1.6, < 2)
+      minitest (>= 5.1)
+      tzinfo (~> 2.0)
+      zeitwerk (~> 2.3)
     addressable (2.8.0)
       public_suffix (>= 2.0.2, < 5.0)
     ast (2.4.2)
+    concurrent-ruby (1.1.9)
     crack (0.4.5)
       rexml
     diff-lcs (1.4.4)
-    faraday (1.4.2)
+    dotenv (2.7.6)
+    faraday (1.7.0)
       faraday-em_http (~> 1.0)
       faraday-em_synchrony (~> 1.0)
       faraday-excon (~> 1.1)
+      faraday-httpclient (~> 1.0.1)
       faraday-net_http (~> 1.0)
       faraday-net_http_persistent (~> 1.1)
+      faraday-patron (~> 1.0)
+      faraday-rack (~> 1.0)
       multipart-post (>= 1.2, < 3)
       ruby2_keywords (>= 0.0.4)
     faraday-em_http (1.0.0)
     faraday-em_synchrony (1.0.0)
     faraday-excon (1.1.0)
+    faraday-httpclient (1.0.1)
     faraday-net_http (1.0.1)
-    faraday-net_http_persistent (1.1.0)
-    faraday_middleware (1.0.0)
+    faraday-net_http_persistent (1.2.0)
+    faraday-patron (1.0.0)
+    faraday-rack (1.0.0)
+    faraday_middleware (1.1.0)
       faraday (~> 1.0)
     hashdiff (1.0.1)
     hashie (4.1.0)
+    i18n (1.8.10)
+      concurrent-ruby (~> 1.0)
     jaro_winkler (1.5.4)
+    minitest (5.14.4)
     multipart-post (2.1.1)
     parallel (1.20.1)
     parser (3.0.1.1)
       ast (~> 2.4.1)
     public_suffix (4.0.6)
     rainbow (3.0.0)
-    rake (10.5.0)
+    rake (13.0.6)
     rexml (3.2.5)
     rspec (3.10.0)
       rspec-core (~> 3.10.0)
@@ -67,14 +86,17 @@ GEM
     rubocop-rspec (1.39.0)
       rubocop (>= 0.68.1)
     ruby-progressbar (1.11.0)
-    ruby2_keywords (0.0.4)
+    ruby2_keywords (0.0.5)
     timecop (0.9.4)
+    tzinfo (2.0.4)
+      concurrent-ruby (~> 1.0)
     unicode-display_width (1.7.0)
     vcr (6.0.0)
     webmock (3.13.0)
       addressable (>= 2.3.6)
       crack (>= 0.3.2)
       hashdiff (>= 0.4.0, < 2.0.0)
+    zeitwerk (2.4.2)
 
 PLATFORMS
   arm64-darwin-20
@@ -82,7 +104,7 @@ PLATFORMS
 
 DEPENDENCIES
   notion-ruby-client!
-  rake (~> 10)
+  rake (~> 13)
   rspec
   rubocop (~> 0.82.0)
   rubocop-performance (~> 1.5.2)

data/README.md

@@ -1,5 +1,8 @@
 # Notion Ruby Client
 
+[![Gem Version](https://badge.fury.io/rb/notion-ruby-client.svg)](http://badge.fury.io/rb/notion-ruby-client)
+[![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)
+
 A Ruby client for the Notion API.
 
 ## Table of Contents
@@ -7,8 +10,28 @@ A Ruby client for the Notion API.
 - [Installation](#installation)
 - [Usage](#usage)
   - [Create a New Bot Integration](#create-a-new-bot-integration)
-  - [Declare the API Token](#declare-the-api-token)
+  - [Declare the API token](#declare-the-api-token)
   - [API Client](#api-client)
+    - [Instantiating a new Notion API client](#instantiating-a-new-notion-api-client)
+    - [Pagination](#pagination)
+- [Endpoints](#endpoints)
+  - [Databases](#databases)
+    - [Query a database](#query-a-database)
+    - [Create a Database](#create-a-database)
+    - [Retrieve a database](#retrieve-a-database)
+    - [List databases](#list-databases)
+  - [Pages](#pages)
+    - [Retrieve a page](#retrieve-a-page)
+    - [Create a page](#create-a-page)
+    - [Update page](#update-page)
+  - [Blocks](#blocks)
+    - [Retrieve block children](#retrieve-block-children)
+    - [Append block children](#append-block-children)
+  - [Users](#users)
+    - [Retrieve a user](#retrieve-a-user)
+    - [List all users](#list-all-users)
+  - [Search](#search)
+- [Acknowledgements](#acknowledgements)
 
 ## Installation
 
@@ -22,15 +45,15 @@ Run `bundle install`.
 
 ## Usage
 
-### Create a New Bot Integration
+### Create a New Integration
 
-To integrate your bot with Notion, you must first [create a new Notion Bot](https://www.notion.so/Getting-started-da32a6fc1bcc4403a6126ee735710d89).
+> :blue_book: **Before you start**
+>
+> 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).
 
-1. Log into the workspace that you want your integration to be associated with.
-2. Confirm that you are an Admin in the workspace (see Settings & Members > Members).
-3. Go to Settings & Members, and click API
+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”).
 
-![A screenshot of the Notion page to create a bot](screenshots/create_notion_bot.png)
+> :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.**
 
 ### Declare the API token
 
@@ -56,36 +79,46 @@ You can specify the token or logger on a per-client basis:
 client = Notion::Client.new(token: '<secret Notion API token>')
 ```
 
-#### Users
+#### Pagination
 
-Get a paginated list of [User objects](https://www.notion.so/User-object-4f8d1a2fc1e54680b5f810ed0c6903a6) for the workspace:
+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.
 
 ```ruby
-client.users_list # retrieves the first page
-
-client.users_list(start_cursor: 'fe2cc560-036c-44cd-90e8-294d5a74cebc')
-
-client.users_list do |page|
-  # paginate through all users
+all_users = []
+client.users_list(page_size: 25) do |page|
+  all_users.concat(page.results)
 end
+all_users # All users, retrieved 25 at a time
 ```
 
-Get a single User:
+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`.
+
+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.
 
 ```ruby
-client.user(id: 'd40e767c-d7af-4b18-a86d-55c61f1e39a4')
+all_users = []
+client.users_list(sleep_interval: 5, max_retries: 20) do |page|
+  # pauses for 5 seconds between each request
+  # gives up after 20 consecutive rate-limited responses
+  all_users.concat(page.results)
+end
+all_users
 ```
 
-#### Databases
+## Endpoints
 
-Gets a paginated array of Page objects contained in the requested database, filtered and ordered according to the filter and sort references provided in the request.
+### Databases
+
+#### Query a database
+
+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.
 
 ```ruby
-client.database_query(id: 'e383bcee-e0d8-4564-9c63-900d307abdb0')  # retrieves the first page
+client.database_query(database_id: 'e383bcee-e0d8-4564-9c63-900d307abdb0')  # retrieves the first page
 
-client.database_query(id: 'e383bcee-e0d8-4564-9c63-900d307abdb0', start_cursor: 'fe2cc560-036c-44cd-90e8-294d5a74cebc')
+client.database_query(database_id: 'e383bcee-e0d8-4564-9c63-900d307abdb0', start_cursor: 'fe2cc560-036c-44cd-90e8-294d5a74cebc')
 
-client.database_query((id: 'e383bcee-e0d8-4564-9c63-900d307abdb0') do |page|
+client.database_query(database_id: 'e383bcee-e0d8-4564-9c63-900d307abdb0') do |page|
   # paginate through all pages
 end
 
@@ -112,28 +145,16 @@ filter = {
     }
   ]
 }
-client.database_query(id: 'e383bcee-e0d8-4564-9c63-900d307abdb0', sort: sort, filter: filter)
+client.database_query(database_id: 'e383bcee-e0d8-4564-9c63-900d307abdb0', sort: sort, filter: filter)
 ```
 
-Get a single Database:
-
-```ruby
-client.database(id: 'e383bcee-e0d8-4564-9c63-900d307abdb0')
-```
+See [Pagination](#pagination) for details about how to iterate through the list.
 
-Lists databases:
+See the full endpoint documentation on [Notion Developers](https://developers.notion.com/reference/post-database-query).
 
-```ruby
-client.databases_list # retrieves the first page
+#### Create a Database
 
-client.databases_list(start_cursor: 'fe2cc560-036c-44cd-90e8-294d5a74cebc')
-
-client.databases_list do |page|
-  # paginate through all databases
-end
-```
-
-Create a Database:
+Creates a database as a subpage in the specified parent page, with the specified properties schema.
 
 ```ruby
 title = [
@@ -144,7 +165,7 @@ title = [
       "link": nil
     }
   }
-],
+]
 properties = {
   "Name": {
     "title": {}
@@ -181,9 +202,76 @@ client.create_database(
 )
 ```
 
-#### Pages
+See the full endpoint documentation on [Notion Developers](https://developers.notion.com/reference/create-a-database).
+
+#### Update a Database
 
-Create a page:
+Updates an existing database as specified by the parameters.
+
+```ruby
+title = [
+  {
+    "text": {
+      "content": "Orbit 💜 Notion"
+    }
+  }
+]
+client.update_database(database_id: 'dd428e9dd3fe4171870da7a1902c748b', title: title)
+```
+
+See the full endpoint documentation on [Notion Developers](https://developers.notion.com/reference/update-a-database).
+
+#### Retrieve a database
+
+Retrieves a [Database object](https://developers.notion.com/reference-link/database) using the ID specified.
+
+```ruby
+client.database(database_id: 'e383bcee-e0d8-4564-9c63-900d307abdb0')
+```
+
+See the full endpoint documentation on [Notion Developers](https://developers.notion.com/reference/retrieve-a-database).
+
+#### List databases
+
+List all [Databases](https://developers.notion.com/reference-link/database) shared with the authenticated integration.
+
+```ruby
+client.databases_list # retrieves the first page
+
+client.databases_list(start_cursor: 'fe2cc560-036c-44cd-90e8-294d5a74cebc')
+
+client.databases_list do |page|
+  # paginate through all databases
+end
+```
+
+See [Pagination](#pagination) for details about how to iterate through the list.
+
+See the full endpoint documentation on [Notion Developers](https://developers.notion.com/reference/list-databases).
+
+### Pages
+
+#### Retrieve a page
+
+Retrieves a [Page object](https://developers.notion.com/reference-link/page) using the ID specified.
+
+> :blue_book: Responses contains page **properties**, not page content. To fetch page content, use the [retrieve block children](#retrieve-block-children) endpoint.
+
+```ruby
+client.page(page_id: 'b55c9c91-384d-452b-81db-d1ef79372b75')
+```
+
+See the full endpoint documentation on [Notion Developers](https://developers.notion.com/reference/retrieve-a-page).
+
+#### Create a page
+
+Creates a new page in the specified database or as a child of an existing page.
+
+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.
+
+If the parent is a page, the only valid property is `title`.
+
+The new page may include page content, described as [blocks](https://developers.notion.com/reference-link/block) in the children parameter.
 
 ```ruby
 properties = {
@@ -241,36 +329,78 @@ client.create_page(
 )
 ```
 
-Retrieve a page:
+See the full endpoint documentation on [Notion Developers](https://developers.notion.com/reference/post-page).
 
-```ruby
-client.page(id: 'b55c9c91-384d-452b-81db-d1ef79372b75')
-```
+#### Update page
+
+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.
 
-Update page properties:
+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.
 
 ```ruby
 properties = {
   "In stock": true
 }
-client.update_page(id: 'b55c9c91-384d-452b-81db-d1ef79372b75', properties: properties)
+client.update_page(page_id: 'b55c9c91-384d-452b-81db-d1ef79372b75', properties: properties)
+```
+
+See the full endpoint documentation on [Notion Developers](https://developers.notion.com/reference/patch-page).
+
+### Blocks
+
+#### Retrieve a block
+
+Retrieves a [Block object](https://developers.notion.com/reference-link/block) using the ID specified.
+
+> :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
+
+```ruby
+client.block(block_id: '9bc30ad4-9373-46a5-84ab-0a7845ee52e6')
+```
+
+See the full endpoint documentation on [Notion Developers](https://developers.notion.com/reference/retrieve-a-block).
+
+#### Update a block
+
+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).
+
+**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.
+
+```ruby
+to_do = {
+  'text': [{
+    'text': { 'content': 'Lacinato kale' }
+    }],
+  'checked': false
+}
+client.update_block(block_id: '9bc30ad4-9373-46a5-84ab-0a7845ee52e6', 'to_do' => to_do)
 ```
 
-#### Blocks
+See the full endpoint documentation on [Notion Developers](https://developers.notion.com/reference/retrieve-a-block).
 
-Retrieve children Block objects at the requested path:
+#### Retrieve block children
+
+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.
 
 ```ruby
-client.block_children(id: 'b55c9c91-384d-452b-81db-d1ef79372b75')
+client.block_children(block_id: 'b55c9c91-384d-452b-81db-d1ef79372b75')
 
-client.block_children(start_cursor: 'fe2cc560-036c-44cd-90e8-294d5a74cebc')
+client.block_children(block_id: 'b55c9c91-384d-452b-81db-d1ef79372b75', start_cursor: 'fe2cc560-036c-44cd-90e8-294d5a74cebc')
 
-client.block_children_list do |page|
+client.block_children(block_id: 'b55c9c91-384d-452b-81db-d1ef79372b75') do |page|
   # paginate through all children
 end
 ```
 
-Creates and appends new children blocks to the parent block in the requested path:
+See [Pagination](#pagination) for details about how to iterate through the list.
+
+See the full endpoint documentation on [Notion Developers](https://developers.notion.com/reference/get-block-children).
+
+#### Append block children
+
+Creates and appends new children blocks to the parent block specified by `block_id`.
+
+Returns a paginated list of newly created first level children block objects.
 
 ```ruby
 children = [
@@ -282,5 +412,65 @@ children = [
     }
   }
 ]
-client.block_append_children(id: 'b55c9c91-384d-452b-81db-d1ef79372b75', children: children)
+client.block_append_children(block_id: 'b55c9c91-384d-452b-81db-d1ef79372b75', children: children)
+```
+
+See the full endpoint documentation on [Notion Developers](https://developers.notion.com/reference/patch-block-children).
+
+### Users
+
+#### Retrieve a user
+
+Retrieves a [User](https://developers.notion.com/reference/user) using the ID specified.
+
+```ruby
+client.user(user_id: 'd40e767c-d7af-4b18-a86d-55c61f1e39a4')
+```
+
+See the full endpoint documentation on [Notion Developers](https://developers.notion.com/reference/get-user).
+
+#### List all users
+
+Returns a paginated list of [Users](https://developers.notion.com/reference/user) for the workspace.
+
+```ruby
+client.users_list # retrieves the first page
+
+client.users_list(start_cursor: 'fe2cc560-036c-44cd-90e8-294d5a74cebc')
+
+client.users_list do |page|
+  # paginate through all users
+end
+```
+
+See [Pagination](#pagination) for details about how to iterate through the list.
+
+See the full endpoint documentation on [Notion Developers](https://developers.notion.com/reference/get-users).
+
+### Search
+
+Searches all pages and child pages that are shared with the integration. The results may include databases.
+
+```ruby
+client.search # search through every available page and database
+
+client.search(query: 'Specific query') # limits which pages are returned by comparing the query to the page title
+
+client.search(filter: { property: 'object', value: 'page' }) # only returns pages
+
+client.search(sort: { direction: 'ascending', timestamp: 'last_edited_time' }) # sorts the results based on the provided criteria.
+
+client.search(start_cursor: 'fe2cc560-036c-44cd-90e8-294d5a74cebc')
+
+client.search do |page|
+  # paginate through all search pages
+end
 ```
+
+See [Pagination](#pagination) for details about how to iterate through the list.
+
+See the full endpoint documentation on [Notion Developers](https://developers.notion.com/reference/post-search).
+
+## Acknowledgements
+
+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).