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

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 526916d20ba8e6c2ec952e750ace9e3e1fb4293ffa0cd317ee8948315cd9b17f
-  data.tar.gz: 14fb8b29995bad4ace873cc85c3ef10fa693322aecee0fbeae24cc1f1dc95092
+  metadata.gz: a9b83ad4b81b6b52c55b8b65bf33f3075733116d91470d237d000a2428f933ea
+  data.tar.gz: f77c9065b91514bfd3acb7ab42c8a8916c022f6725918861ab5ffce47dedd2df
 SHA512:
-  metadata.gz: 2493d2fa1c779c4d6940814bb5669f30932d71022821e97a9f3116f3a69d594a68e892867edad9cdded2e9fa448f1ca04b1b96740c814a723b263374c3119ff0
-  data.tar.gz: 26b90af6ad023ca0a52d950b16e1997b2e3b5e8d1728350b7dbbe43b4651d4cdafa825420eecbd7aa9815a13ddd996a2bc20effb5ff7435ae12af639089e1af5
+  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,35 @@
+### 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)
+- Add support for the new Create database endpoint (@H0R15H0)
+
+### 0.0.7 (2021-06-17)
+
+- Fixes the query parameter for fetching a page resource
+
+### 0.0.6 (2021-06-09)
+
+- Added `Notion-Version` required header to all requests
+
 ### 0.0.5 (2020-04-25)
 
 - Added support for Blocks endpoints

data/CODE_OF_CONDUCT.md

@@ -0,0 +1,128 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our
+community a harassment-free experience for everyone, regardless of age, body
+size, visible or invisible disability, ethnicity, sex characteristics, gender
+identity and expression, level of experience, education, socio-economic status,
+nationality, personal appearance, race, religion, or sexual identity
+and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming,
+diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment for our
+community include:
+
+* Demonstrating empathy and kindness toward other people
+* Being respectful of differing opinions, viewpoints, and experiences
+* Giving and gracefully accepting constructive feedback
+* Accepting responsibility and apologizing to those affected by our mistakes,
+  and learning from the experience
+* Focusing on what is best not just for us as individuals, but for the
+  overall community
+
+Examples of unacceptable behavior include:
+
+* The use of sexualized language or imagery, and sexual attention or
+  advances of any kind
+* Trolling, insulting or derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or email
+  address, without their explicit permission
+* Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Enforcement Responsibilities
+
+Community leaders are responsible for clarifying and enforcing our standards of
+acceptable behavior and will take appropriate and fair corrective action in
+response to any behavior that they deem inappropriate, threatening, offensive,
+or harmful.
+
+Community leaders have the right and responsibility to remove, edit, or reject
+comments, commits, code, wiki edits, issues, and other contributions that are
+not aligned to this Code of Conduct, and will communicate reasons for moderation
+decisions when appropriate.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies when
+an individual is officially representing the community in public spaces.
+Examples of representing our community include using an official e-mail address,
+posting via an official social media account, or acting as an appointed
+representative at an online or offline event.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported to the community leaders responsible for enforcement at
+nicolas@orbit.love.
+All complaints will be reviewed and investigated promptly and fairly.
+
+All community leaders are obligated to respect the privacy and security of the
+reporter of any incident.
+
+## Enforcement Guidelines
+
+Community leaders will follow these Community Impact Guidelines in determining
+the consequences for any action they deem in violation of this Code of Conduct:
+
+### 1. Correction
+
+**Community Impact**: Use of inappropriate language or other behavior deemed
+unprofessional or unwelcome in the community.
+
+**Consequence**: A private, written warning from community leaders, providing
+clarity around the nature of the violation and an explanation of why the
+behavior was inappropriate. A public apology may be requested.
+
+### 2. Warning
+
+**Community Impact**: A violation through a single incident or series
+of actions.
+
+**Consequence**: A warning with consequences for continued behavior. No
+interaction with the people involved, including unsolicited interaction with
+those enforcing the Code of Conduct, for a specified period of time. This
+includes avoiding interactions in community spaces as well as external channels
+like social media. Violating these terms may lead to a temporary or
+permanent ban.
+
+### 3. Temporary Ban
+
+**Community Impact**: A serious violation of community standards, including
+sustained inappropriate behavior.
+
+**Consequence**: A temporary ban from any sort of interaction or public
+communication with the community for a specified period of time. No public or
+private interaction with the people involved, including unsolicited interaction
+with those enforcing the Code of Conduct, is allowed during this period.
+Violating these terms may lead to a permanent ban.
+
+### 4. Permanent Ban
+
+**Community Impact**: Demonstrating a pattern of violation of community
+standards, including sustained inappropriate behavior,  harassment of an
+individual, or aggression toward or disparagement of classes of individuals.
+
+**Consequence**: A permanent ban from any sort of public interaction within
+the community.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage],
+version 2.0, available at
+https://www.contributor-covenant.org/version/2/0/code_of_conduct.html.
+
+Community Impact Guidelines were inspired by [Mozilla's code of conduct
+enforcement ladder](https://github.com/mozilla/diversity).
+
+[homepage]: https://www.contributor-covenant.org
+
+For answers to common questions about this code of conduct, see the FAQ at
+https://www.contributor-covenant.org/faq. Translations are available at
+https://www.contributor-covenant.org/translations.

data/Gemfile.lock

@@ -1,7 +1,9 @@
 PATH
   remote: .
   specs:
-    notion-ruby-client (0.0.5)
+    notion-ruby-client (0.1.0.pre.beta1)
+      activesupport
+      dotenv
       faraday (>= 1.0)
       faraday_middleware
       hashie
@@ -9,33 +11,54 @@ PATH
 GEM
   remote: http://rubygems.org/
   specs:
-    addressable (2.7.0)
+    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.1)
+    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.0)
+    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)
@@ -63,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.12.2)
+    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
@@ -78,7 +104,7 @@ PLATFORMS
 
 DEPENDENCIES
   notion-ruby-client!
-  rake (~> 10)
+  rake (~> 13)
   rspec
   rubocop (~> 0.82.0)
   rubocop-performance (~> 1.5.2)
@@ -88,4 +114,4 @@ DEPENDENCIES
   webmock
 
 BUNDLED WITH
-   2.2.5
+   2.2.16

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
 
@@ -44,7 +67,7 @@ For Rails projects, the snippet above would go to `config/application.rb`.
 
 ### API Client
 
-#### Instanciating a new Notion API client
+#### Instantiating a new Notion API client
 
 ```ruby
 client = Notion::Client.new
@@ -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
+
+### Databases
 
-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.
+#### 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,16 +145,95 @@ 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:
+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-database-query).
+
+#### Create a Database
+
+Creates a database as a subpage in the specified parent page, with the specified properties schema.
 
 ```ruby
-client.database(id: 'e383bcee-e0d8-4564-9c63-900d307abdb0')
+title = [
+  {
+    "type": "text",
+    "text": {
+      "content": "Grocery List",
+      "link": nil
+    }
+  }
+]
+properties = {
+  "Name": {
+    "title": {}
+  },
+  "Description": {
+    "rich_text": {}
+  },
+  "In stock": {
+    "checkbox": {}
+  },
+  "Food group": {
+    "select": {
+      "options": [
+        {
+          "name": "🥦Vegetable",
+          "color": "green"
+        },
+        {
+          "name": "🍎Fruit",
+          "color": "red"
+        },
+        {
+          "name": "💪Protein",
+          "color": "yellow"
+        }
+      ]
+    }
+  }
+}
+client.create_database(
+  parent: { page_id: '98ad959b-2b6a-4774-80ee-00246fb0ea9b' },
+  title: title,
+  properties: properties
+)
 ```
 
-Lists databases:
+See the full endpoint documentation on [Notion Developers](https://developers.notion.com/reference/create-a-database).
+
+#### Update a Database
+
+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
@@ -133,26 +245,54 @@ client.databases_list do |page|
 end
 ```
 
-#### Pages
+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
 
-Create 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 = {
-  "Name": [
-    {
-      "text": {
-        "content": "Tuscan Kale"
+  "Name": {
+    "title": [
+      {
+        "text": {
+          "content": "Tuscan Kale"
+        }
       }
-    }
-  ],
-  "Description": [
-    {
-      "text": {
-        "content": "A dark green leafy vegetable"
+    ]
+  },
+  "Description": {
+    "rich_text": [
+      {
+        "text": {
+          "content": "A dark green leafy vegetable"
+        }
       }
-    }
-  ],
+    ]
+  },
   "Food group": {
     "name": "🥦 Vegetable"
   },
@@ -189,17 +329,148 @@ 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
 
-Update page properties:
+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.
+
+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)
+```
+
+See the full endpoint documentation on [Notion Developers](https://developers.notion.com/reference/retrieve-a-block).
+
+#### 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(block_id: 'b55c9c91-384d-452b-81db-d1ef79372b75')
+
+client.block_children(block_id: 'b55c9c91-384d-452b-81db-d1ef79372b75', start_cursor: 'fe2cc560-036c-44cd-90e8-294d5a74cebc')
+
+client.block_children(block_id: 'b55c9c91-384d-452b-81db-d1ef79372b75') do |page|
+  # paginate through all children
+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-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 = [
+  {
+    "object": 'block',
+    "type": 'heading_2',
+    "heading_2": {
+      "text": [{ "type": 'text', "text": { "content": 'A Second-level Heading' } }]
+    }
+  }
+]
+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).