notion-sdk-ruby 0.5.0 → 0.6.0

data/Rakefile

@@ -1,7 +1,12 @@
-require "bundler/gem_tasks"
-require "rspec/core/rake_task"
-require "standard/rake"
-
-RSpec::Core::RakeTask.new(:spec)
-
-task default: [:spec, :standard]
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+require "standard/rake"
+require "yard"
+
+RSpec::Core::RakeTask.new(:spec)
+
+YARD::Rake::YardocTask.new do |t|
+  t.files = ["lib/**/*.rb"]
+end
+
+task default: [:spec, :standard]

data/bin/console

@@ -1,11 +1,11 @@
-#!/usr/bin/env ruby
-
-require "bundler/setup"
-require "pry"
-require 'dotenv/load'
-
-require "notion-sdk-ruby"
-
-$client = Notion::Client.new(token: ENV["API_SECRET"])
-
-Pry.start
+#!/usr/bin/env ruby
+
+require "bundler/setup"
+require "pry"
+require 'dotenv/load'
+
+require "notion-sdk-ruby"
+
+$client = Notion::Client.new(token: ENV["API_SECRET"])
+
+Pry.start

data/bin/setup

@@ -1,8 +1,8 @@
-#!/usr/bin/env bash
-set -euo pipefail
-IFS=$'\n\t'
-set -vx
-
-bundle install
-
-# Do any other automated setup that you need to do here
+#!/usr/bin/env bash
+set -euo pipefail
+IFS=$'\n\t'
+set -vx
+
+bundle install
+
+# Do any other automated setup that you need to do here

data/lib/notion-sdk-ruby/api/blocks.rb

@@ -0,0 +1,56 @@
+module Notion
+  module Api
+    class BlocksMethods
+      include RequestClient
+
+      # @return [Notion::Api::BlocksChildrenMethods]
+      def children
+        BlocksChildrenMethods.new
+      end
+
+      # Retrieves a Block object using the ID specified.
+      # https://developers.notion.com/reference/retrieve-a-block
+      # @param [String] id block_id
+      # @return [Notion::Block]
+      def retrieve(id)
+        response = get("/v1/blocks/#{id}")
+        Block.new(response.body)
+      end
+
+      # Updates the content for the specified block_id based on the block type.
+      # https://developers.notion.com/reference/update-a-block
+      # @param [String] id block_id
+      # @param [Hash] body
+      # @return [Notion::Block]
+      def update(id, body)
+        response = patch("/v1/blocks/#{id}", body.to_json)
+        Block.new(response.body)
+      end
+    end
+
+    class BlocksChildrenMethods
+      include RequestClient
+
+      # Returns a paginated array of child block objects contained in the block
+      # using the ID specified.
+      # https://developers.notion.com/reference/get-block-children
+      # @param [String] id block_id
+      # @param [Hash] query
+      # @return [Array<Notion::Block>]
+      def list(id, query = {})
+        response = get("/v1/blocks/#{id}/children", query)
+        List.new(response.body)
+      end
+
+      # Creates and appends new children blocks to the parent block_id specified.
+      # https://developers.notion.com/reference/patch-block-children
+      # @param [String] id block_id
+      # @param [Hash] body
+      # @return [Array<Notion::Block>]
+      def append(id, body)
+        response = patch("/v1/blocks/#{id}/children", body.to_json)
+        List.new(response.body)
+      end
+    end
+  end
+end

data/lib/notion-sdk-ruby/api/databases.rb

@@ -0,0 +1,47 @@
+module Notion
+  module Api
+    class DatabasesMethods
+      include RequestClient
+
+      # Retrieves a Database object using the ID specified.
+      # https://developers.notion.com/reference/retrieve-a-database
+      # @param [String] id database_id
+      # @return [Notion::Database]
+      def retrieve(id)
+        response = get("/v1/databases/#{id}")
+        Database.new(response.body)
+      end
+
+      # Gets a list of Pages contained in the database, filtered and ordered according
+      # to the filter conditions and sort criteria provided in the request.
+      # https://developers.notion.com/reference/post-database-query
+      # @param [String] id database_id
+      # @param [Hash] body
+      # @return [Array<Notion::Database>]
+      def query(id, body)
+        response = post("/v1/databases/#{id}/query", body.to_json)
+        List.new(response.body)
+      end
+
+      # Creates a database as a subpage in the specified parent page, with the
+      # specified properties schema.
+      # https://developers.notion.com/reference/create-a-database
+      # @param [Hash] body
+      # @return [Notion::Database]
+      def create(body)
+        response = post("/v1/databases", body.to_json)
+        Database.new(response.body)
+      end
+
+      # Updates an existing database as specified by the parameters.
+      # https://developers.notion.com/reference/update-a-database
+      # @param [String] id database_id
+      # @param [Hash] body
+      # @return [Notion::Database]
+      def update(id, body)
+        response = patch("/v1/databases/#{id}", body.to_json)
+        Database.new(response.body)
+      end
+    end
+  end
+end

data/lib/notion-sdk-ruby/api/pages.rb

@@ -0,0 +1,36 @@
+module Notion
+  module Api
+    class PagesMethods
+      include RequestClient
+
+      # Retrieves a Page object using the ID specified.
+      # https://developers.notion.com/reference/retrieve-a-page
+      # @param [String] id page_id
+      # @return [Notion::Page]
+      def retrieve(id)
+        response = get("/v1/pages/#{id}")
+        Page.new(response.body)
+      end
+
+      # Creates a new page in the specified database or as a child of
+      # an existing page.
+      # https://developers.notion.com/reference/post-page
+      # @param [Hash] body
+      # @return [Notion::Page]
+      def create(body)
+        response = post("/v1/pages", body.to_json)
+        Page.new(response.body)
+      end
+
+      # Updates page property values for the specified page.
+      # https://developers.notion.com/reference/patch-page
+      # @param [String] id page_id
+      # @param [Hash] body
+      # @return [Notion::Page]
+      def update(id, body)
+        response = patch("/v1/pages/#{id}", body.to_json)
+        Page.new(response.body)
+      end
+    end
+  end
+end

data/lib/notion-sdk-ruby/api/search.rb

@@ -0,0 +1,17 @@
+module Notion
+  module Api
+    module SearchMethods
+      include RequestClient
+
+      # Searches all original pages, databases, and child pages/databases
+      # that are shared with the integration.
+      # https://developers.notion.com/reference/post-search
+      # @param [Hash] body
+      # @return [Array]
+      def search(body)
+        response = post("/v1/search", body.to_json)
+        List.new(response.body)
+      end
+    end
+  end
+end

data/lib/notion-sdk-ruby/api/users.rb

@@ -0,0 +1,24 @@
+module Notion
+  module Api
+    class UsersMethods
+      include RequestClient
+
+      # Returns a paginated list of Users for the workspace.
+      # https://developers.notion.com/reference/get-users
+      # @return [Array<Notion::User>]
+      def list
+        response = get("/v1/users")
+        List.new(response.body)
+      end
+
+      # Retrieves a User using the ID specified.
+      # https://developers.notion.com/reference/get-user
+      # @param [String] id user_id
+      # @return [Notion::User]
+      def retrieve(id)
+        response = get("/v1/users/#{id}")
+        User.new(response.body)
+      end
+    end
+  end
+end

data/lib/notion-sdk-ruby/client.rb

@@ -1,27 +1,30 @@
-module Notion
-  class Client
-    include RequestClient
-    include Operations::Search
-
-    def initialize(token:, notion_version: "2021-08-16")
-      Notion.api_token = token
-      Notion.notion_version = notion_version
-    end
-
-    def blocks
-      Blocks.new
-    end
-
-    def databases
-      Databases.new
-    end
-
-    def pages
-      Pages.new
-    end
-
-    def users
-      Users.new
-    end
-  end
-end
+module Notion
+  class Client
+    include Api::SearchMethods
+
+    def initialize(token:, notion_version: "2022-02-22")
+      Notion.api_token = token
+      Notion.notion_version = notion_version
+    end
+
+    # @return [Notion::Api::DatabasesMethods]
+    def databases
+      Api::DatabasesMethods.new
+    end
+
+    # @return [Notion::Api::UsersMethods]
+    def users
+      Api::UsersMethods.new
+    end
+
+    # @return [Notion::Api::BlocksMethods]
+    def blocks
+      Api::BlocksMethods.new
+    end
+
+    # @return [Notion::Api::PagesMethods]
+    def pages
+      Api::PagesMethods.new
+    end
+  end
+end

data/lib/notion-sdk-ruby/config.rb

@@ -1,5 +1,5 @@
-module Notion
-  class Config
-    attr_accessor :api_token, :notion_version
-  end
-end
+module Notion
+  class Config
+    attr_accessor :api_token, :notion_version
+  end
+end

data/lib/notion-sdk-ruby/error.rb

@@ -1,52 +1,52 @@
-# Sourced from notion-sdk-js:
-# https://github.com/makenotion/notion-sdk-js/blob/main/src/errors.ts
-module Notion
-  API_ERROR_CODE = {
-    unauthorized: "unauthorized",
-    restricted_resource: "restricted_resource",
-    object_not_found: "object_not_found",
-    rate_limited: "rate_limited",
-    invalid_json: "invalid_json",
-    invalid_request_url: "invalid_request_url",
-    invalid_request: "invalid_request",
-    validation_error: "validation_error",
-    conflict_error: "conflict_error",
-    internal_server_error: "internal_server_error",
-    service_unavailable: "service_unavailable"
-  }
-
-  class ErrorFactory
-    def self.create(error = {})
-      return NotionError.new("Unknown error.") if error["message"].nil?
-
-      if API_ERROR_CODE.value?(error["code"])
-        APIResponseError.new(error["message"], body: error)
-      elsif error["request"] && error["response"] && error["timings"]
-        HTTPResponseError.new(error["message"], body: error)
-      elsif error["request"] && error["timings"]
-        RequestTimeoutError.new(error["message"], body: error)
-      else
-        NotionError.new(error["message"])
-      end
-    end
-  end
-
-  class NotionError < StandardError
-    attr_reader :message, :body
-
-    def initialize(message = nil, body: nil)
-      @message = message
-      @body = body
-    end
-  end
-
-  class RequestTimeoutError < NotionError; end
-
-  class HTTPResponseError < NotionError; end
-
-  class APIResponseError < NotionError
-    def code
-      body["code"]
-    end
-  end
-end
+# Sourced from notion-sdk-js:
+# https://github.com/makenotion/notion-sdk-js/blob/main/src/errors.ts
+module Notion
+  API_ERROR_CODE = {
+    unauthorized: "unauthorized",
+    restricted_resource: "restricted_resource",
+    object_not_found: "object_not_found",
+    rate_limited: "rate_limited",
+    invalid_json: "invalid_json",
+    invalid_request_url: "invalid_request_url",
+    invalid_request: "invalid_request",
+    validation_error: "validation_error",
+    conflict_error: "conflict_error",
+    internal_server_error: "internal_server_error",
+    service_unavailable: "service_unavailable"
+  }
+
+  class ErrorFactory
+    def self.create(error = {})
+      return NotionError.new("Unknown error.") if error["message"].nil?
+
+      if API_ERROR_CODE.value?(error["code"])
+        APIResponseError.new(error["message"], body: error)
+      elsif error["request"] && error["response"] && error["timings"]
+        HTTPResponseError.new(error["message"], body: error)
+      elsif error["request"] && error["timings"]
+        RequestTimeoutError.new(error["message"], body: error)
+      else
+        NotionError.new(error["message"])
+      end
+    end
+  end
+
+  class NotionError < StandardError
+    attr_reader :message, :body
+
+    def initialize(message = nil, body: nil)
+      @message = message
+      @body = body
+    end
+  end
+
+  class RequestTimeoutError < NotionError; end
+
+  class HTTPResponseError < NotionError; end
+
+  class APIResponseError < NotionError
+    def code
+      body["code"]
+    end
+  end
+end

data/lib/notion-sdk-ruby/models/block.rb

@@ -1,4 +1,7 @@
-module Notion
-  class Block < OpenStruct
-  end
-end
+module Notion
+  # A block object represents content within Notion.
+  #
+  # https://developers.notion.com/reference/block
+  class Block < OpenStruct
+  end
+end

data/lib/notion-sdk-ruby/models/database.rb

@@ -1,4 +1,7 @@
-module Notion
-  class Database < OpenStruct
-  end
-end
+module Notion
+  # Database objects describe the property schema of a database in Notion.
+  #
+  # https://developers.notion.com/reference/database
+  class Database < OpenStruct
+  end
+end

data/lib/notion-sdk-ruby/models/list.rb

@@ -1,27 +1,49 @@
-module Notion
-  class List
-    attr_reader :data, :next_cursor, :has_more
-
-    def initialize(response_body)
-      @data = response_body["results"].map do |d|
-        get_model(d["object"]).new(d)
-      end
-
-      @next_cursor = response_body["next_cursor"]
-      @has_more = response_body["has_more"]
-    end
-
-    def get_model(object_name)
-      case object_name
-      when "block"
-        Block
-      when "database"
-        Database
-      when "page"
-        Page
-      when "user"
-        User
-      end
-    end
-  end
-end
+module Notion
+  # The List object is an intermediate object that helps with pagination.
+  #
+  # https://developers.notion.com/reference/pagination
+  class List
+    # An array of endpoint-dependent objects
+    # @return [Array<Notion::User>]
+    # @return [Array<Notion::Database>]
+    # @return [Array<Notion::Page>]
+    # @return [Array<Notion::Block>]
+    attr_reader :data
+
+    # Used to retrieve the next page of results by passing the value as the
+    # start_cursor parameter to the same endpoint.
+    # @return [nil] if has_more is true.
+    # @return [string] if has_more is false.
+    attr_reader :next_cursor
+
+    # When the response includes the end of the list, false. Otherwise, true.
+    # @return [boolean]
+    attr_reader :has_more
+
+    def initialize(response_body)
+      @data = response_body["results"].map do |d|
+        get_model(d["object"]).new(d)
+      end
+
+      @next_cursor = response_body["next_cursor"]
+      @has_more = response_body["has_more"]
+    end
+
+    private
+
+    def get_model(object_name)
+      case object_name
+      when "block"
+        Block
+      when "database"
+        Database
+      when "page"
+        Page
+      when "user"
+        User
+      else
+        raise NotionError.new("unimplemented object type")
+      end
+    end
+  end
+end

data/lib/notion-sdk-ruby/models/page.rb

@@ -1,4 +1,7 @@
-module Notion
-  class Page < OpenStruct
-  end
-end
+module Notion
+  # The Page object contains the property values of a single Notion page.
+  #
+  # https://developers.notion.com/reference/page
+  class Page < OpenStruct
+  end
+end

data/lib/notion-sdk-ruby/models/user.rb

@@ -1,4 +1,7 @@
-module Notion
-  class User < OpenStruct
-  end
-end
+module Notion
+  # The User object represents a user in a Notion workspace.
+  #
+  # https://developers.notion.com/reference/user
+  class User < OpenStruct
+  end
+end

data/lib/notion-sdk-ruby/request_client.rb

@@ -1,45 +1,45 @@
-module Notion
-  module RequestClient
-    def get(*args)
-      handle_request(:get, *args)
-    end
-
-    def post(*args)
-      handle_request(:post, *args)
-    end
-
-    def patch(*args)
-      handle_request(:patch, *args)
-    end
-
-    def delete(*args)
-      handle_request(:delete, *args)
-    end
-
-    private
-
-    def handle_request(method, *args)
-      faraday_client.public_send(method, *args)
-    rescue Faraday::ClientError => error
-      error_details = JSON.parse(error.response[:body])
-      raise ErrorFactory.create(error_details)
-    rescue JSON::ParserError => error
-      raise NotionError.new(error.message)
-    end
-
-    def faraday_client
-      @faraday_client ||= Faraday.new(
-        url: "https://api.notion.com",
-        headers: {
-          "Content-Type" => "application/json",
-          "Notion-Version" => Notion.config.notion_version,
-          "Authorization" => "Bearer #{Notion.config.api_token}"
-        }
-      ) do |f|
-        f.request :json
-        f.response :json
-        f.use Faraday::Response::RaiseError
-      end
-    end
-  end
-end
+module Notion
+  module RequestClient
+    private
+
+    def get(*args)
+      handle_request(:get, *args)
+    end
+
+    def post(*args)
+      handle_request(:post, *args)
+    end
+
+    def patch(*args)
+      handle_request(:patch, *args)
+    end
+
+    def delete(*args)
+      handle_request(:delete, *args)
+    end
+
+    def handle_request(method, *args)
+      faraday_client.public_send(method, *args)
+    rescue Faraday::ClientError => error
+      error_details = JSON.parse(error.response[:body])
+      raise ErrorFactory.create(error_details)
+    rescue JSON::ParserError => error
+      raise NotionError.new(error.message)
+    end
+
+    def faraday_client
+      @faraday_client ||= Faraday.new(
+        url: "https://api.notion.com",
+        headers: {
+          "Content-Type" => "application/json",
+          "Notion-Version" => Notion.config.notion_version,
+          "Authorization" => "Bearer #{Notion.config.api_token}"
+        }
+      ) do |f|
+        f.request :json
+        f.response :json
+        f.use Faraday::Response::RaiseError
+      end
+    end
+  end
+end

data/lib/notion-sdk-ruby/version.rb

@@ -1,3 +1,3 @@
-module Notion
-  VERSION = "0.5.0"
-end
+module Notion
+  VERSION = "0.6.0"
+end