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

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a9b83ad4b81b6b52c55b8b65bf33f3075733116d91470d237d000a2428f933ea
-  data.tar.gz: f77c9065b91514bfd3acb7ab42c8a8916c022f6725918861ab5ffce47dedd2df
+  metadata.gz: 79512758dde3ce8092694e5358ede8acdadb47fe58f3f21bed15c6715c4d21a5
+  data.tar.gz: 863b240db55feeef22c9578d9519df009fc4010aba3c2d784e757de15b80f2d3
 SHA512:
-  metadata.gz: b080379a4840e4b925a6b7bcb5e4c5ea7a25a85856947281cc95eddcc718dd16bb14466d127fca2d2b02a028e4f5df62ea3225ac1a614057578144e43220288c
-  data.tar.gz: aebf1260e3c10c54abebf62259beb35ab0d4ad520c8f26de98a163ed26d5e1989b09ef3d2189622a0a9b34552ac0b0d0085c567d3cd3488fc4a788fd0ba082a9
+  metadata.gz: f4705cd8542fc5537df2e4889523a59a7bbaca00b3c190fd6ab0a681c4f8419793f0593f831a96ea4bb4324a2065d9f05decffbba1f01ce0d3df89b8fe82265c
+  data.tar.gz: 6ec3e8d68bc0ff75d9c6440800fe118c79884cabf560dd28927e663a38d22c877cb2a14aafa3f2c4eb91361bf69f3f8aab04622faa1d26f281a2c66249a4deaa

data/.devcontainer/Dockerfile

@@ -0,0 +1,5 @@
+# See here for image contents: https://github.com/microsoft/vscode-dev-containers/tree/v0.191.1/containers/ruby/.devcontainer/base.Dockerfile
+
+# [Choice] Ruby version: 3, 3.0, 2, 2.7, 2.6
+ARG VARIANT="3.0"
+FROM mcr.microsoft.com/vscode/devcontainers/ruby:0-${VARIANT}

data/.devcontainer/boot.sh

@@ -0,0 +1 @@
+bundle install

data/.devcontainer/devcontainer.json

@@ -0,0 +1,30 @@
+// For format details, see https://aka.ms/devcontainer.json. For config options, see the README at:
+// https://github.com/microsoft/vscode-dev-containers/tree/v0.191.1/containers/ruby
+{
+	"name": "Ruby",
+	"build": {
+		"dockerfile": "Dockerfile",
+		"context": "..",
+		"args": {
+			// Update 'VARIANT' to pick a Ruby version: 3, 3.0, 2, 2.7, 2.6
+			"VARIANT": "2.7",
+		}
+	},
+
+	// Set *default* container specific settings.json values on container create.
+	"settings": {},
+
+	// Add the IDs of extensions you want installed when the container is created.
+	"extensions": [
+		"rebornix.Ruby"
+	],
+
+	// Use 'forwardPorts' to make a list of ports inside the container available locally.
+	// "forwardPorts": [],
+
+	// Use 'postCreateCommand' to run commands after the container is created.
+	"postCreateCommand": ".devcontainer/boot.sh",
+
+	// Comment out connect as root instead. More info: https://aka.ms/vscode-remote/containers/non-root.
+	"remoteUser": "vscode"
+}

data/CHANGELOG.md

@@ -1,3 +1,21 @@
+### 1.0.0-beta1 (2022-03-24)
+
+#### New
+
+- Add support for the following new endpoints:
+  - [Delete a block](https://developers.notion.com/reference/get-block-children)
+  - [Retrieve your token's bot user](https://developers.notion.com/reference/get-self)
+  - [Retrieve a page property item](https://developers.notion.com/reference/retrieve-a-page-property)
+- Update Notion API Version to `2022-02-22` (thanks @hkob!)
+- Remove the following deprecated endpoint:
+  - [List databases](https://developers.notion.com/reference/get-databases)
+- Add Codespaces and CONTRIBUTING.md command for better DX
+- Overhauled documentation
+
+#### Upgrade instructions
+
+- Please refer to the Notion Changelog to see breaking changes for version `2022-02-22`: https://developers.notion.com/changelog/releasing-notion-version-2022-02-22
+
 ### 0.1.0-beta1 (2021-08-29)
 
 #### New

data/CONTRIBUTING.md

@@ -0,0 +1,51 @@
+# CONTRIBUTING
+
+_This project is intended to be a safe, welcoming space for collaboration. By participating in this project you agree to abide by the [Contributor Code of Conduct](CODE_OF_CONDUCT.md)._
+
+Hi there! We're thrilled that you'd like to contribute to this project. Your help is essential for keeping it great.
+
+## Running the project
+
+### GitHub Codespaces
+
+This repository includes configuration for GitHub Codespaces, making it easy to set up a cloud-based development environment. Follow [GitHub's guide](https://docs.github.com/en/codespaces/developing-in-codespaces/creating-a-codespace#creating-a-codespace) to get started.
+
+The Codespaces environment has the dependencies all installed, and should be ready to tinker with. Once your Codespace is set up, you can check that everything works as intended by running the specs:
+
+```
+bundle exec rake
+```
+
+### Running the project locally
+
+You can also install the project on your machine:
+
+```
+git clone https://github.com/orbit-love/notion-ruby-client.git
+cd notion-ruby-client
+# if you do not have bundler installed already, run
+# $ gem install bundle
+# to install it
+bundle install
+```
+
+You can check that everything works as intended by running the specs:
+
+```
+bundle exec rake
+```
+
+## Interactive console
+
+You can run
+
+```
+bin/console
+```
+
+to start an IRB (interactive Ruby console) session with all the gem files loaded.
+Usually, you’d start such sessions by defining your `client`:
+
+```
+client = Notion::Client.new(token: <Your Notion API token>)
+```

data/Gemfile.lock

@@ -1,17 +1,17 @@
 PATH
   remote: .
   specs:
-    notion-ruby-client (0.1.0.pre.beta1)
-      activesupport
+    notion-ruby-client (1.0.0.pre.beta1)
+      activesupport (~> 6)
       dotenv
       faraday (>= 1.0)
       faraday_middleware
-      hashie
+      hashie (~> 5)
 
 GEM
   remote: http://rubygems.org/
   specs:
-    activesupport (6.1.4.1)
+    activesupport (6.1.5)
       concurrent-ruby (~> 1.0, >= 1.0.2)
       i18n (>= 1.6, < 2)
       minitest (>= 5.1)
@@ -20,38 +20,42 @@ GEM
     addressable (2.8.0)
       public_suffix (>= 2.0.2, < 5.0)
     ast (2.4.2)
-    concurrent-ruby (1.1.9)
+    concurrent-ruby (1.1.10)
     crack (0.4.5)
       rexml
     diff-lcs (1.4.4)
     dotenv (2.7.6)
-    faraday (1.7.0)
+    faraday (1.10.0)
       faraday-em_http (~> 1.0)
       faraday-em_synchrony (~> 1.0)
       faraday-excon (~> 1.1)
-      faraday-httpclient (~> 1.0.1)
+      faraday-httpclient (~> 1.0)
+      faraday-multipart (~> 1.0)
       faraday-net_http (~> 1.0)
-      faraday-net_http_persistent (~> 1.1)
+      faraday-net_http_persistent (~> 1.0)
       faraday-patron (~> 1.0)
       faraday-rack (~> 1.0)
-      multipart-post (>= 1.2, < 3)
+      faraday-retry (~> 1.0)
       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-multipart (1.0.3)
+      multipart-post (>= 1.2, < 3)
     faraday-net_http (1.0.1)
     faraday-net_http_persistent (1.2.0)
     faraday-patron (1.0.0)
     faraday-rack (1.0.0)
-    faraday_middleware (1.1.0)
+    faraday-retry (1.0.3)
+    faraday_middleware (1.2.0)
       faraday (~> 1.0)
     hashdiff (1.0.1)
-    hashie (4.1.0)
-    i18n (1.8.10)
+    hashie (5.0.0)
+    i18n (1.10.0)
       concurrent-ruby (~> 1.0)
     jaro_winkler (1.5.4)
-    minitest (5.14.4)
+    minitest (5.15.0)
     multipart-post (2.1.1)
     parallel (1.20.1)
     parser (3.0.1.1)
@@ -96,10 +100,11 @@ GEM
       addressable (>= 2.3.6)
       crack (>= 0.3.2)
       hashdiff (>= 0.4.0, < 2.0.0)
-    zeitwerk (2.4.2)
+    zeitwerk (2.5.4)
 
 PLATFORMS
   arm64-darwin-20
+  ruby
   x86_64-linux
 
 DEPENDENCIES

data/README.md

@@ -18,16 +18,22 @@ A Ruby client for the Notion API.
   - [Databases](#databases)
     - [Query a database](#query-a-database)
     - [Create a Database](#create-a-database)
+    - [Update a Database](#update-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)
+    - [Retrieve a page property item](#retrieve-a-page-property-item)
   - [Blocks](#blocks)
+    - [Retrieve a block](#retrieve-a-block)
+    - [Update a block](#update-a-block)
+    - [Delete a block](#delete-a-block)
     - [Retrieve block children](#retrieve-block-children)
     - [Append block children](#append-block-children)
   - [Users](#users)
+    - [Retrieve your token's bot user](#retrieve-your-tokens-bot-user)
     - [Retrieve a user](#retrieve-a-user)
     - [List all users](#list-all-users)
   - [Search](#search)
@@ -125,22 +131,22 @@ end
 # Filter and sort the database
 sort = [
   {
-    "property": "Last ordered",
-    "direction": "ascending"
+    'property': 'Last ordered',
+    'direction': 'ascending'
   }
 ]
 filter = {
-  "or": [
+  'or': [
     {
-      "property": "In stock",
-      "checkbox": {
-        "equals": true
+      'property': 'In stock',
+      'checkbox': {
+        'equals': true
       }
     },
     {
-      "property": "Cost of next trip",
-      "number": {
-        "greater_than_or_equal_to": 2
+      'property': 'Cost of next trip',
+      'number': {
+        'greater_than_or_equal_to': 2
       }
     }
   ]
@@ -159,37 +165,37 @@ Creates a database as a subpage in the specified parent page, with the specified
 ```ruby
 title = [
   {
-    "type": "text",
-    "text": {
-      "content": "Grocery List",
-      "link": nil
+    'type': 'text',
+    'text': {
+      'content': 'Grocery List',
+      'link': nil
     }
   }
 ]
 properties = {
-  "Name": {
-    "title": {}
+  'Name': {
+    'title': {}
   },
-  "Description": {
-    "rich_text": {}
+  'Description': {
+    'rich_text': {}
   },
-  "In stock": {
-    "checkbox": {}
+  'In stock': {
+    'checkbox': {}
   },
-  "Food group": {
-    "select": {
-      "options": [
+  'Food group': {
+    'select': {
+      'options': [
         {
-          "name": "🥦Vegetable",
-          "color": "green"
+          'name': '🥦Vegetable',
+          'color': 'green'
         },
         {
-          "name": "🍎Fruit",
-          "color": "red"
+          'name': '🍎Fruit',
+          'color': 'red'
         },
         {
-          "name": "💪Protein",
-          "color": "yellow"
+          'name': '💪Protein',
+          'color': 'yellow'
         }
       ]
     }
@@ -211,8 +217,8 @@ Updates an existing database as specified by the parameters.
 ```ruby
 title = [
   {
-    "text": {
-      "content": "Orbit 💜 Notion"
+    'text': {
+      'content': 'Orbit 💜 Notion'
     }
   }
 ]
@@ -275,47 +281,54 @@ The new page may include page content, described as [blocks](https://developers.
 
 ```ruby
 properties = {
-  "Name": {
-    "title": [
+  'Name': {
+    'title': [
       {
-        "text": {
-          "content": "Tuscan Kale"
+        'text': {
+          'content': 'Tuscan Kale'
         }
       }
     ]
   },
-  "Description": {
-    "rich_text": [
+  'Description': {
+    'rich_text': [
       {
-        "text": {
-          "content": "A dark green leafy vegetable"
+        'text': {
+          'content': 'A dark green leafy vegetable'
         }
       }
     ]
   },
-  "Food group": {
-    "name": "🥦 Vegetable"
+  'Food group': {
+    'select': {
+      'name': '🥦 Vegetable'
+    }
   },
-  "Price": 2.5
+  'Price': {
+    'number': 2.5
+  }
 }
 children = [
   {
-    "object": "block",
-    "type": "heading_2",
-    "heading_2": {
-      "text": [{ "type": "text", "text": { "content": "Lacinato kale" } }]
+    'object': 'block',
+    'type': 'heading_2',
+    'heading_2': {
+      'rich_text': [{
+        'type": 'text',
+        'text': { 'content': 'Lacinato kale' }
+      }]
     }
   },
   {
-    "object": "block",
-    "type": "paragraph",
-    "paragraph": {
-      "text": [
+    'object': 'block',
+    'type": 'paragraph',
+    'paragraph': {
+      'rich_text': [
         {
-          "type": "text",
-          "text": {
-            "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.",
-            "link": { "url": "https://en.wikipedia.org/wiki/Lacinato_kale" }
+          'type': 'text',
+          'text': {
+            '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.',
+            'link': { 'url': 'https://en.wikipedia.org/wiki/Lacinato_kale' }
           }
         }
       ]
@@ -339,13 +352,30 @@ If the parent is a database, the new [property values](https://developers.notion
 
 ```ruby
 properties = {
-  "In stock": true
+  'In stock': {
+    'checkbox': true
+  }
 }
 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).
 
+#### Retrieve a page property item
+
+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.
+
+To obtain `property_id`'s, use the [Retrieve a database endpoint](#retrieve-a-database).
+
+```ruby
+client.page_property_item(
+  page_id: 'b55c9c91-384d-452b-81db-d1ef79372b75',
+  property_id: 'aBcD123'
+)
+```
+
+See the full endpoint documentation on [Notion Developers](https://developers.notion.com/reference/retrieve-a-page-property).
+
 ### Blocks
 
 #### Retrieve a block
@@ -368,7 +398,8 @@ Updates the content for the specified block_id based on the block type. Supporte
 
 ```ruby
 to_do = {
-  'text': [{
+  'rich_text': [{
+    'type': 'text',
     'text': { 'content': 'Lacinato kale' }
     }],
   'checked': false
@@ -378,6 +409,18 @@ client.update_block(block_id: '9bc30ad4-9373-46a5-84ab-0a7845ee52e6', 'to_do' =>
 
 See the full endpoint documentation on [Notion Developers](https://developers.notion.com/reference/retrieve-a-block).
 
+#### Delete a block
+
+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.
+
+To restore the block with the API, use the [Update a block](#update-a-block) or [Update page](#update-page) respectively.
+
+```ruby
+client.delete_block(block_id: '9bc30ad4-9373-46a5-84ab-0a7845ee52e6')
+```
+
+See the full endpoint documentation on [Notion Developers](https://developers.notion.com/reference/delete-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.
@@ -407,8 +450,11 @@ children = [
   {
     "object": 'block',
     "type": 'heading_2',
-    "heading_2": {
-      "text": [{ "type": 'text', "text": { "content": 'A Second-level Heading' } }]
+    'heading_2': {
+      'rich_text': [{
+        'type': 'text',
+        'text': { 'content': 'A Second-level Heading' }
+      }]
     }
   }
 ]
@@ -419,6 +465,16 @@ See the full endpoint documentation on [Notion Developers](https://developers.no
 
 ### Users
 
+#### Retrieve your token's bot user
+
+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.
+
+```ruby
+client.me
+```
+
+See the full endpoint documentation on [Notion Developers](https://developers.notion.com/reference/get-self).
+
 #### Retrieve a user
 
 Retrieves a [User](https://developers.notion.com/reference/user) using the ID specified.

data/lib/notion/api/endpoints/blocks.rb

@@ -32,6 +32,22 @@ module Notion
           patch("blocks/#{options[:block_id]}", options.except(:block_id))
         end
 
+        #
+        # Sets a Block object, 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.
+        #
+        # To restore the block with the API, use the Update a block or
+        # Update page respectively.
+        #
+        # @option options [id] :block_id
+        #   Block to get children info on.
+        def delete_block(options = {})
+          throw ArgumentError.new('Required arguments :block_id missing') if options[:block_id].nil?
+          delete("blocks/#{options[:block_id]}")
+        end
+
         #
         # Returns a paginated array of Block objects contained in the
         # block of the requested path using the ID specified.

data/lib/notion/api/endpoints/databases.rb

@@ -101,27 +101,6 @@ module Notion
           throw ArgumentError.new('Required arguments :database_id missing') if options[:database_id].nil?
           get("databases/#{options[:database_id]}")
         end
-
-        #
-        # Returns a paginated list of Databases objects for the workspace.
-        #
-        # @option options [UUID] :start_cursor
-        # Paginate through collections of data by setting the cursor parameter
-        # to a start_cursor attribute returned by a previous request's next_cursor.
-        # Default value fetches the first "page" of the collection.
-        # See pagination for more detail.
-        #
-        # @option options [integer] :page_size
-        #   The number of items from the full list desired in the response. Maximum: 100
-        def databases_list(options = {})
-          if block_given?
-            Pagination::Cursor.new(self, :databases_list, options).each do |page|
-              yield page
-            end
-          else
-            get('databases', options)
-          end
-        end
       end
     end
   end

data/lib/notion/api/endpoints/pages.rb

@@ -15,7 +15,7 @@ module Notion
         #   Set to true to retrieve an archived page; must be false or omitted to
         #   retrieve a page that has not been archived. Defaults to false.
         def page(options = {})
-          throw ArgumentError.new('Required arguments :page_id missing') if options[:page_id].nil?
+          throw ArgumentError.new('Required argument :page_id missing') if options[:page_id].nil?
           get("pages/#{options[:page_id]}")
         end
 
@@ -38,7 +38,7 @@ module Notion
         # @option options [Object] :children
         #   An optional array of Block objects representing the Page’s content
         def create_page(options = {})
-          throw ArgumentError.new('Required arguments :parent.database_id missing') if options.dig(:parent, :database_id).nil?
+          throw ArgumentError.new('Required argument :parent.database_id missing') if options.dig(:parent, :database_id).nil?
           post("pages", options)
         end
 
@@ -60,9 +60,26 @@ module Notion
         #   appears in Notion, or property ID. value object Object containing a value
         #   specific to the property type, e.g. {"checkbox": true}.
         def update_page(options = {})
-          throw ArgumentError.new('Required arguments :page_id missing') if options[:page_id].nil?
+          throw ArgumentError.new('Required argument :page_id missing') if options[:page_id].nil?
           patch("pages/#{options[:page_id]}", options.except(:page_id))
         end
+
+        #
+        # 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 list of property item values.
+        #
+        # @option options [id] :page_id
+        #   Page to get info on.
+        #
+        # @option options [id] :property_id
+        #   Property to get info on.
+        #
+        def page_property_item(options = {})
+          throw ArgumentError.new('Required argument :page_id missing') if options[:page_id].nil?
+          throw ArgumentError.new('Required argument :property_id missing') if options[:property_id].nil?
+          get("pages/#{options[:page_id]}/properties/#{options[:property_id]}")
+        end
       end
     end
   end

data/lib/notion/api/endpoints/users.rb

@@ -4,6 +4,14 @@ module Notion
   module Api
     module Endpoints
       module Users
+        #
+        # Retrieves the bot 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.
+        def me
+          get("users/me")
+        end
+
         #
         # Retrieves a User object using the ID specified in the request.
         #

data/lib/notion/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 module Notion
-  VERSION = '0.1.0-beta1'
-  NOTION_REQUEST_VERSION = '2021-08-16'
+  VERSION = '1.0.0-beta1'
+  NOTION_REQUEST_VERSION = '2022-02-22'
 end

data/notion-ruby-client.gemspec

@@ -15,11 +15,11 @@ Gem::Specification.new do |s|
   s.homepage = 'http://github.com/orbit-love/notion-ruby-client'
   s.licenses = ['MIT']
   s.summary = 'Notion API client for Ruby.'
-  s.add_dependency 'activesupport'
+  s.add_dependency 'activesupport', '~> 6'
   s.add_dependency 'dotenv'
   s.add_dependency 'faraday', '>= 1.0'
   s.add_dependency 'faraday_middleware'
-  s.add_dependency 'hashie'
+  s.add_dependency 'hashie', '~> 5'
   s.add_development_dependency 'rake', '~> 13'
   s.add_development_dependency 'rspec'
   s.add_development_dependency 'rubocop', '~> 0.82.0'

data/spec/fixtures/notion/block.yml

@@ -14,7 +14,7 @@ http_interactions:
       Authorization:
       - Bearer <NOTION_API_TOKEN>
       Notion-Version:
-      - '2021-08-16'
+      - '2022-02-22'
       Accept-Encoding:
       - gzip;q=1.0,deflate;q=0.6,identity;q=0.3
   response:
@@ -139,7 +139,7 @@ http_interactions:
       - 68679732dfea3acb-CDG
     body:
       encoding: UTF-8
-      string: '{"object":"block","id":"32af3324-ba02-4516-ae88-5728a4d569f4","created_time":"2021-05-01T17:13:00.000Z","last_edited_time":"2021-08-29T17:18:00.000Z","has_children":true,"type":"paragraph","paragraph":{"text":[{"type":"text","text":{"content":"A
+      string: '{"object":"block","id":"32af3324-ba02-4516-ae88-5728a4d569f4","created_time":"2021-05-01T17:13:00.000Z","last_edited_time":"2021-08-29T17:18:00.000Z","has_children":true,"type":"paragraph","paragraph":{"rich_text":[{"type":"text","text":{"content":"A
         paragraph with childrens","link":null},"annotations":{"bold":false,"italic":false,"strikethrough":false,"underline":false,"code":false,"color":"default"},"plain_text":"A
         paragraph with childrens","href":null}]}}'
   recorded_at: Sun, 29 Aug 2021 17:45:01 GMT