notionrb 1.3.0

data/bin/console

@@ -0,0 +1,31 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "bundler/setup"
+require "dotenv/load"
+require "notion-ruby-client"
+
+# You can add fixtures and/or initialization code here to make experimenting
+# with your gem easier. You can also use a different console, if you like.
+
+# (If you use this, don't forget to add pry to your Gemfile!)
+# require "pry"
+# Pry.start
+
+require "irb"
+
+def reload!(print = true)
+  puts 'Reloading ...' if print
+  # Main project directory.
+  root_dir = File.expand_path('..', __dir__)
+  # Directories within the project that should be reloaded.
+  reload_dirs = %w{lib}
+  # Loop through and reload every file in all relevant project directories.
+  reload_dirs.each do |dir|
+    Dir.glob("#{root_dir}/#{dir}/**/*.rb").each { |f| load(f) }
+  end
+  # Return true when complete.
+  true
+end
+
+IRB.start(__FILE__)

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

@@ -0,0 +1,100 @@
+# frozen_string_literal: true
+
+module Notion
+  module Api
+    module Endpoints
+      module Blocks
+        #
+        # Retrieves a Block object using the ID specified.
+        #
+        # @option options [id] :block_id
+        #   Block to get children info on.
+        def block(options = {})
+          throw ArgumentError.new('Required arguments :block_id missing') if options[:block_id].nil?
+          get("blocks/#{options[:block_id]}")
+        end
+
+        #
+        # Updates the content for the specified block_id based on
+        # the block type. Supported fields based on the block object
+        # type (see Block object for available fields and the
+        # expected input for each field).
+        #
+        # @option options [id] :block_id
+        #   Block to get children info on.
+        #
+        # @option options [string] {type}
+        #   The block object type value with the properties to be
+        #   updated. Currently only text (for supported block types)
+        #   and checked (for to_do blocks) fields can be updated.
+        def update_block(options = {})
+          block_id = options.delete(:block_id)
+          throw ArgumentError.new('Required arguments :block_id missing') if block_id.nil?
+          patch("blocks/#{block_id}", options)
+        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.
+        #
+        # Returns a 404 HTTP response if any of the following are true:
+        # - the ID does not exist
+        # - the bot doesn't have access to the block with the given ID
+        #
+        # Returns a 400 or 429 HTTP response if the request exceeds Notion's Request limits.
+        #
+        # @option options [id] :block_id
+        #   Block to get children info on.
+        def block_children(options = {})
+          throw ArgumentError.new('Required arguments :block_id missing') if options[:block_id].nil?
+          if block_given?
+            Pagination::Cursor.new(self, :block_children, options).each do |page|
+              yield page
+            end
+          else
+            block_id = options.delete(:block_id)
+            get("blocks/#{block_id}/children", options)
+          end
+        end
+
+        #
+        # Creates and appends new children blocks to the parent block
+        # in the requested path using the ID specified. Returns the Block
+        # object being appended to.
+        #
+        # Returns a 404 HTTP response if any of the following are true:
+        # - the ID does not exist
+        # - the bot doesn't have access to the block with the given ID
+        #
+        # Returns a 400 or 429 HTTP response if the request exceeds Notion's Request limits.
+        #
+        # @option options [id] :block_id
+        #   Block to append children to.
+        #
+        # @option options [[Object]] :children
+        #   Children blocks to append
+        def block_append_children(options = {})
+          block_id = options.delete(:block_id)
+          throw ArgumentError.new('Required arguments :block_id missing') if block_id.nil?
+          patch("blocks/#{block_id}/children", options)
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+module Notion
+  module Api
+    module Endpoints
+      module Comments
+        #
+        # Retrieves a list of un-resolved Comment objects from a page or block.
+        #
+        # @option options [id] :block_id
+        #   Block or page id to fetch comments for.
+        #
+        # @option options [start_cursor] :start_cursor
+        #   If supplied, this endpoint will return a page
+        #   of results starting after the cursor provided.
+        #   If not supplied, this endpoint will return the
+        #   first page of results.
+        #
+        # @option options [page_size] :page_size
+        #   The number of items from the full list desired in the response.
+        #   Maximum: 100
+        #
+        def retrieve_comments(options = {})
+          throw ArgumentError.new('Required arguments :block_id missing') if options[:block_id].nil?
+          if block_given?
+            Pagination::Cursor.new(self, :retrieve_comments, options).each do |page|
+              yield page
+            end
+          else
+            get('comments', options)
+          end
+        end
+
+        #
+        # Creates a comment in a page or existing discussion thread.
+        #   There are two locations you can add a new comment to:
+        #     - A page
+        #     - An existing discussion thread
+        #   If the intention is to add a new comment to a page, a parent object
+        #   must be provided in the body params. Alternatively, if a new comment
+        #   is being added to an existing discussion thread, the discussion_id string
+        #   must be provided in the body params. Exactly one of these parameters must be provided.
+        #
+        # @option options [Object] :parent
+        #   A page parent. Either this or a discussion_id is required (not both).
+        #
+        # @option options [UUID] :discussion_id
+        #   A UUID identifier for a discussion thread. Either this or a parent object is required (not both).
+        #
+        # @option options [Object] :rich_text
+        #   A rich text object.
+        def create_comment(options = {})
+          if options.dig(:parent, :page_id).nil? && options[:discussion_id].nil?
+            throw ArgumentError.new('Required argument :page_id or :discussion_id missing')
+          end
+          throw ArgumentError.new('Required argument :rich_text missing') if options[:rich_text].nil?
+          post('comments', options)
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,102 @@
+# frozen_string_literal: true
+
+module Notion
+  module Api
+    module Endpoints
+      module DataSources
+        #
+        # Gets a paginated array of Page objects contained in the requested data source,
+        # filtered and ordered according to the filter and sort objects provided in the request.
+        #
+        # Starting with Notion-Version 2025-09-03, databases can contain multiple data
+        # sources. Querying is done against a data source, not the database itself.
+        # Use #database to look up a database's data source ids.
+        #
+        # @option options [id] :data_source_id
+        #   Data source to query.
+        #
+        # @option options [Object] :filter
+        #   When supplied, limits which pages are returned based on the provided criteria.
+        #
+        # @option options [[Object]] :sorts
+        #   When supplied, sorts the results based on the provided criteria.
+        #
+        # @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 data_source_query(options = {})
+          throw ArgumentError.new('Required arguments :data_source_id missing') if options[:data_source_id].nil?
+          if block_given?
+            Pagination::Cursor.new(self, :data_source_query, options).each do |page|
+              yield page
+            end
+          else
+            data_source_id = options.delete(:data_source_id)
+            post("data_sources/#{data_source_id}/query", options)
+          end
+        end
+
+        #
+        # Adds a new data source to an existing database.
+        #
+        # @option options [Object] :parent
+        #   Parent of the data source, referencing an existing database via :database_id.
+        #
+        # @option options [Object] :properties
+        #   Property schema of data source.
+        #   The keys are the names of properties as they appear in Notion and the values are
+        #   property schema objects. Each data source must have exactly one property schema
+        #   object of type "title".
+        #
+        # @option options [Object] :title
+        #   Title of this data source.
+        def create_data_source(options = {})
+          throw ArgumentError.new('Required arguments :parent.database_id missing') if options.dig(:parent, :database_id).nil?
+          throw ArgumentError.new('Required arguments :properties missing') if options.dig(:properties).nil?
+          post('data_sources', options)
+        end
+
+        #
+        # Updates an existing data source as specified by the parameters.
+        #
+        # @option options [id] :data_source_id
+        #   Data source to update.
+        #
+        # @option options [Object] :title
+        #   Title of data source as it appears in Notion. An array of rich text objects.
+        #   If omitted, the title will remain unchanged.
+        #
+        # @option options [Object] :properties
+        #   Updates to the property schema of a data source.
+        #   If updating an existing property, the keys are the names or IDs
+        #   of the properties as they appear in Notion and the values
+        #   are property schema objects. If adding a new property, the key is
+        #   the name of the property and the value is a property schema object.
+        def update_data_source(options = {})
+          data_source_id = options.delete(:data_source_id)
+          throw ArgumentError.new('Required arguments :data_source_id missing') if data_source_id.nil?
+          patch("data_sources/#{data_source_id}", options)
+        end
+
+        #
+        # Retrieves a Data source object using the ID specified in the request.
+        #
+        # Returns a 404 HTTP response if the data source doesn't exist, or if the bot
+        # doesn't have access to the data source. Returns a 429 HTTP response if the
+        # request exceeds Notion's Request limits.
+        #
+        # @option options [id] :data_source_id
+        #   Data source to get info on.
+        def data_source(options = {})
+          throw ArgumentError.new('Required arguments :data_source_id missing') if options[:data_source_id].nil?
+          get("data_sources/#{options[:data_source_id]}")
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,134 @@
+# frozen_string_literal: true
+
+module Notion
+  module Api
+    module Endpoints
+      module Databases
+        #
+        # Gets a paginated array of Page object s contained in the requested database,
+        # filtered and ordered according to the filter and sort objects provided in the request.
+        #
+        # Filters are similar to the filters provided in the Notion UI. Filters operate
+        # on database properties and can be combined. If no filter is provided, all the
+        # pages in the database will be returned with pagination.
+        #
+        # Sorts are similar to the sorts provided in the Notion UI. Sorts operate on
+        # database properties and can be combined. The order of the sorts in the request
+        # matter, with earlier sorts taking precedence over later ones.
+        #
+        # @deprecated As of Notion-Version 2025-09-03, databases can hold multiple data
+        #   sources, and querying is performed against a data source id, not a database
+        #   id. Use {#data_source_query} instead, resolving the data source id via
+        #   {#database}'s :data_sources field.
+        #
+        # @option options [id] :database_id
+        #   Database to query.
+        #
+        # @option options [Object] :filter
+        #   When supplied, limits which pages are returned based on the provided criteria.
+        #
+        # @option options [[Object]] :sorts
+        #   When supplied, sorts the results based on the provided criteria.
+        #
+        # @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 database_query(options = {})
+          throw ArgumentError.new('Required arguments :database_id missing') if options[:database_id].nil?
+          logger.warn('[DEPRECATED] #database_query is deprecated as of Notion-Version 2025-09-03 ' \
+                      'and only works for databases with a single data source. Use #data_source_query instead.')
+          if block_given?
+            Pagination::Cursor.new(self, :database_query, options).each do |page|
+              yield page
+            end
+          else
+            database_id = options.delete(:database_id)
+            post("databases/#{database_id}/query", options)
+          end
+        end
+
+        #
+        # Creates a new database, with a single data source, in the specified page.
+        #
+        # As of Notion-Version 2025-09-03, the property schema is nested under
+        # :initial_data_source instead of being a top-level :properties argument. For
+        # convenience, a top-level :properties option is still accepted here and is
+        # wrapped into :initial_data_source automatically.
+        #
+        # @option options [Object] :parent
+        #   Parent of the database, which is always going to be a page.
+        #
+        # @option options [Object] :title
+        #   Title of this database.
+        #
+        # @option options [Object] :initial_data_source
+        #   The initial data source for this database, e.g. { properties: { ... } }.
+        #
+        # @option options [Object] :properties
+        #   Shorthand for initial_data_source[:properties]. Property schema of the
+        #   database's initial data source.
+        #   The keys are the names of properties as they appear in Notion and the values are
+        #   property schema objects. Property Schema Object is a metadata that controls
+        #   how a database property behaves, e.g. {"checkbox": {}}.
+        #   Each database must have exactly one database property schema object of type "title".
+        def create_database(options = {})
+          throw ArgumentError.new('Required arguments :parent.page_id missing') if options.dig(:parent, :page_id).nil?
+          throw ArgumentError.new('Required arguments :title missing') if options.dig(:title).nil?
+
+          properties = options.delete(:properties)
+          if options[:initial_data_source].nil?
+            throw ArgumentError.new('Required arguments :properties missing') if properties.nil?
+
+            options[:initial_data_source] = { properties: properties }
+          end
+
+          post('databases', options)
+        end
+
+        #
+        # Updates an existing database as specified by the parameters.
+        #
+        # As of Notion-Version 2025-09-03, this endpoint only accepts database-level
+        # fields (:title, :description, :icon, :cover, :is_inline, :in_trash,
+        # :is_locked, :parent). Updating a :properties schema is now done per data
+        # source via {#update_data_source}.
+        #
+        # @option options [id] :database_id
+        #   Database to update.
+        #
+        # @option options [Object] :title
+        #   Title of database as it appears in Notion. An array of rich text objects.
+        #   If omitted, the database title will remain unchanged.
+        #
+        def update_database(options = {})
+          database_id = options.delete(:database_id)
+          throw ArgumentError.new('Required arguments :database_id missing') if database_id.nil?
+          patch("databases/#{database_id}", options)
+        end
+
+        #
+        # Retrieves a Database object using the ID specified in the request.
+        #
+        # Returns a 404 HTTP response if the database doesn't exist, or if the bot
+        # doesn't have access to the database. Returns a 429 HTTP response if the
+        # request exceeds Notion's Request limits.
+        #
+        # As of Notion-Version 2025-09-03, the response's :data_sources field lists
+        # the data source ids and names that belong to this database, for use with
+        # {#data_source_query}, {#data_source} and {#update_data_source}.
+        #
+        # @option options [id] :database_id
+        #   Database to get info on.
+        def database(options = {})
+          throw ArgumentError.new('Required arguments :database_id missing') if options[:database_id].nil?
+          get("databases/#{options[:database_id]}")
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,95 @@
+# frozen_string_literal: true
+
+module Notion
+  module Api
+    module Endpoints
+      module Pages
+        #
+        # Retrieves a 📄Page object  using the ID specified in the request path.
+        # Note that this version of the API only exposes page properties, not page content
+        #
+        # @option options [id] :page_id
+        #   Page to get info on.
+        #
+        # @option options [bool] :archived
+        #   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 argument :page_id missing') if options[:page_id].nil?
+          get("pages/#{options[:page_id]}")
+        end
+
+        #
+        # Creates a new page in the specified database (or data source) or as a child of an existing page.
+        # Note that this iteration of the API will only expose page properties, not
+        # page content, as described in the data model.
+        #
+        # As of Notion-Version 2025-09-03, pages should be created under a data source
+        # (:parent.data_source_id) rather than a database. :parent.database_id remains
+        # supported for databases with a single data source.
+        #
+        # @option options [Object] :parent
+        #   Parent of the page: a data source, a database, or a page.
+        #
+        # @option options [Object] :properties
+        #   Properties of this page.
+        #   The schema for the page's keys and values is described by the properties of
+        #   the data source this page belongs to. key string Name of a property as it
+        #   appears in Notion, or property ID. value object Object containing a value
+        #   specific to the property type, e.g. {"checkbox": true}.
+        #
+        # @option options [Object] :children
+        #   An optional array of Block objects representing the Page’s content
+        def create_page(options = {})
+          if options.dig(:parent, :data_source_id).nil? &&
+             options.dig(:parent, :database_id).nil? &&
+             options.dig(:parent, :page_id).nil?
+            throw ArgumentError.new('Required argument :parent.data_source_id, :parent.database_id or :parent.page_id required')
+          end
+
+          post("pages", options)
+        end
+
+        #
+        # Updates a page by setting the values of any properties specified in the
+        # JSON body of the request. Properties that are not set via parameters will
+        # remain unchanged.
+        #
+        # Note that this iteration of the API will only expose page properties, not page
+        # content, as described in the data model.
+        #
+        # @option options [id] :page_id
+        #   Page to get info on.
+        #
+        # @option options [Object] :properties
+        #   Properties of this page.
+        #   The schema for the page's keys and values is described by the properties of
+        #   the database this page belongs to. key string Name of a property as it
+        #   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 = {})
+          page_id = options.delete(:page_id)
+          throw ArgumentError.new('Required argument :page_id missing') if page_id.nil?
+          patch("pages/#{page_id}", options)
+        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
+end

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

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module Notion
+  module Api
+    module Endpoints
+      module Search
+        #
+        # Searches all pages and child pages that are shared with the integration.
+        # The results may include databases.
+        #
+        # @option options [string] :query
+        #   When supplied, limits which pages are returned by comparing the query to the page title.
+        #
+        # @option options [Object] :filter
+        #   When supplied, filters the results based on the provided criteria.
+        #
+        # @option options [[Object]] :sorts
+        #   When supplied, sorts the results based on the provided criteria.
+        #   Limitation: Currently only a single sort is allowed and is limited to last_edited_time.
+        #
+        # @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 search(options = {})
+          if block_given?
+            Pagination::Cursor.new(self, :search, options).each do |page|
+              yield page
+            end
+          else
+            post('search', options)
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+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.
+        #
+        # @option options [id] :user_id
+        #   User to get info on.
+        def user(options = {})
+          throw ArgumentError.new('Required arguments :user_id missing') if options[:user_id].nil?
+          get("users/#{options[:user_id]}")
+        end
+
+        #
+        # Returns a paginated list of User 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 users_list(options = {})
+          if block_given?
+            Pagination::Cursor.new(self, :users_list, options).each do |page|
+              yield page
+            end
+          else
+            get("users", options)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/notion/api/endpoints.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+require_relative 'endpoints/blocks'
+require_relative 'endpoints/databases'
+require_relative 'endpoints/data_sources'
+require_relative 'endpoints/pages'
+require_relative 'endpoints/users'
+require_relative 'endpoints/search'
+require_relative 'endpoints/comments'
+
+module Notion
+  module Api
+    module Endpoints
+      include Blocks
+      include Databases
+      include DataSources
+      include Pages
+      include Users
+      include Search
+      include Comments
+    end
+  end
+end

data/lib/notion/api/error.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+module Notion
+  module Api
+    Error = Errors::NotionError
+  end
+end

data/lib/notion/api/errors/internal_error.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+module Notion
+  module Api
+    module Errors
+      class ServerError < InternalError; end
+      class ParsingError < ServerError; end
+      class HttpRequestError < ServerError; end
+      class TimeoutError < HttpRequestError; end
+      class UnavailableError < HttpRequestError; end
+    end
+  end
+end

data/lib/notion/api/errors/notion_error.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+module Notion
+  module Api
+    module Errors
+      class NotionError < ::Faraday::Error
+        attr_reader :response
+
+        def initialize(message, details, response = nil)
+          super("#{message} #{details}")
+          @response = response
+        end
+      end
+    end
+  end
+end