notion 1.0.0

data/lib/notion_api/client.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+require_relative 'core'
+
+module NotionAPI
+  # acts as the 'main interface' to the methods of this package.
+  class Client < Core
+    attr_reader :token_v2, :active_user_header
+
+    def initialize(token_v2, active_user_header = nil)
+      @token_v2 = token_v2
+      @active_user_header = active_user_header
+      super(token_v2, active_user_header)
+    end
+  end
+end

data/lib/notion_api/core.rb

@@ -0,0 +1,217 @@
+# frozen_string_literal: true
+
+require_relative 'utils'
+require 'httparty'
+
+module NotionAPI
+  # the initial methods available to an instantiated Cloent object are defined
+  class Core
+    include Utils
+    @options = { 'cookies' => { :token_v2 => nil, 'x-active-user-header' => nil }, 'headers' => { 'Content-Type' => 'application/json' } }
+    @type_whitelist = 'divider'
+
+    class << self
+      attr_reader :options, :type_whitelist, :token_v2, :active_user_header
+    end
+
+    attr_reader :clean_id, :cookies, :headers
+
+    def initialize(token_v2, active_user_header)
+      @@token_v2 = token_v2
+      @@active_user_header = active_user_header
+    end
+
+    def get_page(url_or_id)
+      # ! retrieve a Notion Page Block and return its instantiated class object.
+      # ! url_or_id -> the block ID or URL : ``str``
+      clean_id = extract_id(url_or_id)
+
+      request_body = {
+        pageId: clean_id,
+        chunkNumber: 0,
+        limit: 100,
+        verticalColumns: false
+      }
+      jsonified_record_response = get_all_block_info(clean_id, request_body)
+      i = 0
+      while jsonified_record_response.empty? || jsonified_record_response['block'].empty?
+        return {} if i >= 10
+
+        jsonified_record_response = get_all_block_info(clean_id, request_body)
+        i += 1
+      end
+
+      block_id = clean_id
+      block_title = extract_title(clean_id, jsonified_record_response)
+      block_type = extract_type(clean_id, jsonified_record_response)
+      block_parent_id = extract_parent_id(clean_id, jsonified_record_response)
+
+      raise 'the URL or ID passed to the get_page method must be that of a Page Block.' if block_type != 'page'
+
+      PageBlock.new(block_id, block_title, block_parent_id)
+    end
+
+    def children(url_or_id = @id)
+      # ! retrieve the children of a block. If the block has no children, return []. If it does, return the instantiated class objects associated with each child.
+      # ! url_or_id -> the block ID or URL : ``str``
+
+      children_ids = children_ids(url_or_id)
+      if children_ids.empty?
+        []
+      else
+        children_class_instances = []
+        children_ids.each { |child| children_class_instances.push(get(child)) }
+        children_class_instances
+      end
+    end
+
+    def children_ids(url_or_id = @id)
+      # ! retrieve the children IDs of a block.
+      # ! url_or_id -> the block ID or URL : ``str``
+      clean_id = extract_id(url_or_id)
+      request_body = {
+        pageId: clean_id,
+        chunkNumber: 0,
+        limit: 100,
+        verticalColumns: false
+      }
+      jsonified_record_response = get_all_block_info(clean_id, request_body)
+      i = 0
+      while jsonified_record_response.empty?
+        return {} if i >= 10
+
+        jsonified_record_response = get_all_block_info(clean_id, request_body)
+        i += 1
+      end
+
+      jsonified_record_response['block'][clean_id]['value']['content'] || []
+    end
+
+    private
+
+    def get_notion_id(body)
+      # ! retrieves a users ID from the headers of a Notion response object.
+      # ! body -> the body to send in the request : ``Hash``
+      Core.options['cookies'][:token_v2] = @@token_v2
+      Core.options['headers']['x-notion-active-user-header'] = @@active_user_header
+      cookies = Core.options['cookies']
+      headers = Core.options['headers']
+      request_url = URLS[:GET_BLOCK]
+
+      response = HTTParty.post(
+        request_url,
+        body: body.to_json,
+        cookies: cookies,
+        headers: headers
+      )
+      response.headers['x-notion-user-id']
+    end
+
+    def get_last_page_block_id(url_or_id)
+      # ! retrieve and return the last child ID of a block.
+      # ! url_or_id -> the block ID or URL : ``str``
+      children_ids(url_or_id).empty? ? [] : children_ids(url_or_id)[-1]
+    end
+
+    def get_all_block_info(_clean_id, body)
+      # ! retrieves all info pertaining to a block Id.
+      # ! clean_id -> the block ID or URL cleaned : ``str``
+      Core.options['cookies'][:token_v2] = @@token_v2
+      Core.options['headers']['x-notion-active-user-header'] = @active_user_header
+      cookies = Core.options['cookies']
+      headers = Core.options['headers']
+
+      request_url = URLS[:GET_BLOCK]
+
+      response = HTTParty.post(
+        request_url,
+        body: body.to_json,
+        cookies: cookies,
+        headers: headers
+      )
+
+      JSON.parse(response.body)['recordMap']
+    end
+
+    def filter_nil_blocks(jsonified_record_response)
+      # ! removes any blocks that are empty [i.e. have no title / content]
+      # ! jsonified_record_responses -> parsed JSON representation of a notion response object : ``Json``
+      jsonified_record_response.empty? || jsonified_record_response['block'].empty? ? nil : jsonified_record_response['block']
+    end
+
+    def extract_title(clean_id, jsonified_record_response)
+      # ! extract title from core JSON Notion response object.
+      # ! clean_id -> the cleaned block ID: ``str``
+      # ! jsonified_record_response -> parsed JSON representation of a notion response object : ``Json``
+      filter_nil_blocks = filter_nil_blocks(jsonified_record_response)
+      if filter_nil_blocks.nil? || filter_nil_blocks[clean_id].nil? || filter_nil_blocks[clean_id]['value']['properties'].nil?
+        nil
+      else
+        # titles for images are called source, while titles for text-based blocks are called title, so lets dynamically grab it
+        # https://stackoverflow.com/questions/23765996/get-all-keys-from-ruby-hash/23766007
+        title_value = filter_nil_blocks[clean_id]['value']['properties'].keys[0]
+        Core.type_whitelist.include?(filter_nil_blocks[clean_id]['value']['type']) ? nil : jsonified_record_response['block'][clean_id]['value']['properties'][title_value].flatten[0]
+
+      end
+    end
+
+    def extract_collection_title(_clean_id, collection_id, jsonified_record_response)
+      # ! extract title from core JSON Notion response object.
+      # ! clean_id -> the cleaned block ID: ``str``
+      # ! collection_id -> the collection ID: ``str``
+      # ! jsonified_record_response -> parsed JSON representation of a notion response object : ``Json``
+      jsonified_record_response['collection'][collection_id]['value']['name'].flatten.join if jsonified_record_response['collection']
+    end
+
+    def extract_type(clean_id, jsonified_record_response)
+      # ! extract type from core JSON response object.
+      # ! clean_id -> the block ID or URL cleaned : ``str``
+      # ! jsonified_record_response -> parsed JSON representation of a notion response object : ``Json``
+      filter_nil_blocks = filter_nil_blocks(jsonified_record_response)
+      if filter_nil_blocks.nil?
+        nil
+      else
+        filter_nil_blocks[clean_id]['value']['type']
+
+      end
+    end
+
+    def extract_parent_id(clean_id, jsonified_record_response)
+      # ! extract parent ID from core JSON response object.
+      # ! clean_id -> the block ID or URL cleaned : ``str``
+      # ! jsonified_record_response -> parsed JSON representation of a notion response object : ``Json``
+      jsonified_record_response.empty? || jsonified_record_response['block'].empty? ? {} : jsonified_record_response['block'][clean_id]['value']['parent_id']
+    end
+
+    def extract_collection_id(clean_id, jsonified_record_response)
+      # ! extract the collection ID
+      # ! clean_id -> the block ID or URL cleaned : ``str``
+      # ! jsonified_record_response -> parsed JSON representation of a notion response object : ``Json``
+      jsonified_record_response['block'][clean_id]['value']['collection_id']
+    end
+
+    def extract_view_ids(clean_id, jsonified_record_response)
+      jsonified_record_response['block'][clean_id]['value']['view_ids'] || []
+    end
+
+    def extract_id(url_or_id)
+      # ! parse and clean the URL or ID object provided.
+      # ! url_or_id -> the block ID or URL : ``str``
+      http_or_https = url_or_id.match(/^(http|https)/) # true if http or https in url_or_id...
+      if (url_or_id.length == 36) && ((url_or_id.split('-').length == 5) && !http_or_https)
+        # passes if url_or_id is perfectly formatted already...
+        url_or_id
+      elsif (http_or_https && (url_or_id.split('-').last.length == 32)) || (!http_or_https && (url_or_id.length == 32))
+        # passes if either:
+        # 1. a URL is passed as url_or_id and the ID at the end is 32 characters long or
+        # 2. a URL is not passed and the ID length is 32 [aka unformatted]
+        pattern = [8, 13, 18, 23]
+        id = url_or_id.split('-').last
+        pattern.each { |index| id.insert(index, '-') }
+        id
+      else
+        raise ArgumentError, 'Expected a Notion page URL or a page ID. Please consult the documentation for further information.'
+      end
+    end
+  end
+end

data/lib/notion_api/markdown.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Notion
+  class Markdown
+    # ! convert user input formatted with markdown (**hi** is bold, *hi* is italic, etc.) -> notion-understood stylings.
+  end
+end

data/lib/notion_api/utils.rb

@@ -0,0 +1,518 @@
+# frozen_string_literal: true
+
+module Utils
+  # ! defines utility functions and static variables for this application.
+  URLS = {
+    GET_BLOCK: 'https://www.notion.so/api/v3/loadPageChunk',
+    UPDATE_BLOCK: 'https://www.notion.so/api/v3/saveTransactions',
+    GET_COLLECTION: 'https://www.notion.so/api/v3/queryCollection'
+  }.freeze
+
+  class BlockComponents
+    # ! Each function defined here builds one component that is included in each request sent to Notions backend.
+    # ! Each request sent will contain multiple components.
+    def self.create(block_id, block_type)
+      # ! payload for creating a block.
+      # ! block_id -> id of the new block : ``str``
+      # ! block_type -> type of block to create : ``cls``
+      table = 'block'
+      path = []
+      command = 'update'
+      timestamp = DateTime.now.strftime('%Q')
+      {
+        id: block_id,
+        table: table,
+        path: path,
+        command: command,
+        args: {
+          id: block_id,
+          type: block_type,
+          properties: {},
+          created_time: timestamp,
+          last_edited_time: timestamp
+        }
+      }
+    end
+
+    def self.title(id, title)
+      # ! payload for updating the title of a block
+      # ! id -> the ID to update the title of : ``str``
+      table = 'block'
+      path = %w[properties title]
+      command = 'set'
+
+      {
+        id: id,
+        table: table,
+        path: path,
+        command: command,
+        args: [[title]]
+      }
+    end
+
+    def self.last_edited_time(id)
+      # ! payload for updating the last edited time
+      # ! id -> either the block ID or parent ID : ``str``
+      timestamp = DateTime.now.strftime('%Q')
+      table = 'block'
+      path = ['last_edited_time']
+      command = 'set'
+
+      {
+        table: table,
+        id: id,
+        path: path,
+        command: command,
+        args: timestamp
+      }
+    end
+
+    def self.convert_type(id, block_class_to_convert_to)
+      # ! payload for converting a block to a different type.
+      # ! id -> id of the block to convert : ``str``
+      # ! block_class_to_convert_to -> type to convert to block to: ``NotionAPI::<Block_Type>``
+      table = 'block'
+      path = []
+      command = 'update'
+
+      {
+        id: id,
+        table: table,
+        path: path,
+        command: command,
+        args: {
+          type: block_class_to_convert_to.notion_type
+        }
+      }
+    end
+
+    def self.set_parent_to_alive(block_parent_id, new_block_id)
+      # ! payload for setting a blocks parent ID to 'alive'
+      # ! block_parent_id -> the blocks parent ID : ``str``
+      # ! new_block_id -> the new block ID, who is a child of the parent : ``str``
+      table = 'block'
+      path = []
+      command = 'update'
+      parent_table = 'block'
+      alive = true
+      {
+        id: new_block_id,
+        table: table,
+        path: path,
+        command: command,
+        args: {
+          parent_id: block_parent_id,
+          parent_table: parent_table,
+          alive: alive
+        }
+      }
+    end
+
+    def self.set_block_to_dead(block_id)
+      # ! payload for setting a block to dead (alive == true)
+      # ! block_id -> the block ID to 'kill' : ``str``
+      table = 'block'
+      path = []
+      command = 'update'
+      alive = false
+
+      {
+        id: block_id,
+        table: table,
+        path: path,
+        command: command,
+        args: {
+          alive: alive
+        }
+      }
+    end
+
+    def self.duplicate(block_type, block_title, block_id, new_block_id, user_notion_id, contents)
+      # ! payload for duplicating a block. Most properties should be
+      # ! inherited from the block class the method is invoked on.
+      # ! block_type -> type of block that is being duplicated : ``cls``
+      # ! block_title -> title of block : ``str``
+      # ! block_id -> id of block: ``str``
+      # ! new_block_id -> id of new block : ``str``
+      # ! user_notion_id -> ID of notion user : ``str``
+      # ! contents -> The children of the block
+      timestamp = DateTime.now.strftime('%Q')
+      table = 'block'
+      path = []
+      command = 'update'
+
+      {
+        id: new_block_id,
+        table: table,
+        path: path,
+        command: command,
+        args: {
+          id: new_block_id,
+          version: 10,
+          type: block_type,
+          properties: {
+            title: [[block_title]]
+          },
+          content: contents, # root-level blocks
+          created_time: timestamp,
+          last_edited_time: timestamp,
+          created_by_table: 'notion_user',
+          created_by_id: user_notion_id,
+          last_edited_by_table: 'notion_user',
+          last_edited_by_id: user_notion_id,
+          copied_from: block_id
+        }
+      }
+    end
+
+    def self.parent_location_add(block_parent_id, block_id)
+      # ! payload for adding a parent
+      # ! block_parent_id -> the parent id of the block : ``str``
+      # ! block_id -> the id of the block : ``str``
+      table = 'block'
+      path = []
+      command = 'update'
+      parent_table = 'block'
+      alive = true
+
+      {
+        id: block_id,
+        table: table,
+        path: path,
+        command: command,
+        args: {
+          parent_id: block_parent_id,
+          parent_table: parent_table,
+          alive: alive
+        }
+      }
+    end
+
+    def self.block_location_add(block_parent_id, block_id, new_block_id = nil, target, command)
+      # ! payload for duplicating a block. Most properties should be
+      # ! inherited from the block class the method is invoked on.
+      # ! block_parent_id -> id of parent block : ``str``
+      # ! block_id -> id of block: ``str``
+      # ! new_block_id -> id of the new block: ``str``
+      # ! target -> the ID of the target block : ``str``
+      # ! command -> the position of the block, before or after, in relation to the target : ``str``
+      table = 'block'
+      path = ['content']
+
+      args = if command == 'listAfter'
+               {
+                 after: target || block_id,
+                 id: new_block_id || block_id
+               }
+             else
+               {
+                 before: target || block_id,
+                 id: new_block_id || block_id
+               }
+             end
+
+      {
+        table: table,
+        id: block_parent_id, # ID of the parent for the new block. It should be the block that the method is invoked on.
+        path: path,
+        command: command,
+        args: args
+      }
+    end
+
+    def self.block_location_remove(block_parent_id, block_id)
+      # ! removes a notion block
+      # ! block_parent_id -> the parent ID of the block to remove : ``str``
+      # ! block_id -> the ID of the block to remove : ``str``
+      table = 'block'
+      path = ['content']
+      command = 'listRemove'
+      {
+        table: table,
+        id: block_parent_id, # ID of the parent for the new block. It should be the block that the method is invoked on.
+        path: path,
+        command: command,
+        args: {
+          id: block_id
+        }
+      }
+    end
+
+    def self.checked_todo(block_id, standardized_check_val)
+      # ! payload for setting a "checked" value for TodoBlock.
+      # ! block_id -> the ID of the block to remove : ``str``
+      # ! standardized_check_val -> tyes/no value, determines the checked property of the block : ``str``
+      table = 'block'
+      path = ['properties']
+      command = 'update'
+      {
+        id: block_id,
+        table: table,
+        path: path,
+        command: command,
+        args: {
+          checked: [[standardized_check_val]]
+        }
+      }
+    end
+
+    def self.update_codeblock_language(block_id, coding_language)
+      # ! update the language for a codeblock
+      # ! block_id -> id of the code block
+      # ! coding_language -> language to change the block to.
+      table = 'block'
+      path = ['properties']
+      command = 'update'
+
+      {
+        id: block_id,
+        table: table,
+        path: path,
+        command: command,
+        args: {
+          language: [[coding_language]]
+        }
+      }
+    end
+  end
+
+  class CollectionViewComponents
+    def self.create_collection_view(new_block_id, collection_id, view_ids)
+      # ! payload for creating a collection view
+      # ! new_block_id -> id of the new block
+      # ! collection_id -> ID of the collection.
+      # ! view_ids -> id of the view
+      table = 'block'
+      command = 'update'
+      path = []
+      type = 'collection_view'
+      properties = {}
+      timestamp = DateTime.now.strftime('%Q')
+
+      {
+        id: new_block_id,
+        table: table,
+        path: path,
+        command: command,
+        args: {
+          id: new_block_id,
+          type: type,
+          collection_id: collection_id,
+          view_ids: [
+            view_ids
+          ],
+          properties: properties,
+          created_time: timestamp,
+          last_edited_time: timestamp
+        }
+      }
+    end
+
+    def self.set_collection_blocks_alive(new_block_id, collection_id)
+      # ! payload for setting the collection blocks to alive.
+      # ! new_block_id -> id of the new block
+      # ! collection_id -> ID of the collection.
+      table = 'block'
+      path = []
+      command = 'update'
+      parent_table = 'collection'
+      alive = true
+      type = 'page'
+      properties = {}
+      timestamp = DateTime.now.strftime('%Q')
+
+      {
+        id: new_block_id,
+        table: table,
+        path: path,
+        command: command,
+        args: {
+          id: new_block_id,
+          type: type,
+          parent_id: collection_id,
+          parent_table: parent_table,
+          alive: alive,
+          properties: properties,
+          created_time: timestamp,
+          last_edited_time: timestamp
+        }
+      }
+    end
+
+    def self.set_view_config(new_block_id, view_id, children_ids)
+      # ! payload for setting the configurations of the view.
+      # ! new_block_id -> id of the new block
+      # ! view_id -> id of the view
+      # ! children_ids -> IDs for the children of the collection.
+      table = 'collection_view'
+      path = []
+      command = 'update'
+      version = 0
+      type = 'table'
+      name = 'Default View'
+      parent_table = 'block'
+      alive = true
+
+      {
+        id: view_id,
+        table: table,
+        path: path,
+        command: command,
+        args: {
+          id: view_id,
+          version: version,
+          type: type,
+          name: name,
+          page_sort: children_ids,
+          parent_id: new_block_id,
+          parent_table: parent_table,
+          alive: alive
+        }
+      }
+    end
+
+    def self.set_collection_columns(collection_id, new_block_id, data)
+      # ! payload for setting the columns of the table.
+      # ! collection_id -> ID of the collection.
+      # ! new_block_id -> id of the new block
+      # ! data -> json data to insert into table.
+      col_names = data[0].keys
+
+      schema_conf = {}
+      col_names.each_with_index do |_name, i|
+        if i.zero?
+          schema_conf[:title] = { name: col_names[i], type: 'title' }
+        else
+          schema_conf[col_names[i]] = { name: col_names[i], type: 'text' }
+        end
+      end
+      {
+        id: collection_id,
+        table: 'collection',
+        path: [],
+        command: 'update',
+        args: {
+          id: collection_id,
+          schema: schema_conf,
+          parent_id: new_block_id,
+          parent_table: 'block',
+          alive: true
+        }
+      }
+    end
+
+    def self.set_collection_title(collection_title, collection_id)
+      # ! payload for setting the title of the collection.
+      # ! collection_title -> title of the collection.
+      # ! collection_id -> ID of the collection.
+      table = 'collection'
+      path = ['name']
+      command = 'set'
+
+      {
+        id: collection_id,
+        table: table,
+        path: path,
+        command: command,
+        args: [[collection_title]]
+      }
+    end
+
+    def self.insert_data(block_id, column, value)
+      # ! payload for inserting data into the table.
+      # ! block_id -> the ID of the block : ``str``
+      # ! column -> the name of the column to insert data into.
+      # ! value -> the value to insert into the column.
+      table = 'block'
+      path = [
+        'properties',
+        column
+      ]
+      command = 'set'
+
+      {
+        id: block_id,
+        table: table,
+        path: path,
+        command: command,
+        args: [[value]]
+      }
+    end
+
+    def self.add_new_row(new_block_id)
+      # ! payload for adding a new row to the table.
+      # ! new_block_id -> the ID of the new row : ``str``
+      table = 'block'
+      path = []
+      command = 'set'
+      type = 'page'
+
+      {
+        id: new_block_id,
+        table: table,
+        path: path,
+        command: command,
+        args: {
+          type: type,
+          id: new_block_id,
+          version: 1
+        }
+      }
+    end
+
+    def self.query_collection(collection_id, view_id, search_query = '')
+      # ! payload for querying the table for data.
+      # ! collection_id -> the collection ID : ``str``
+      # ! view_id -> the view ID : ``str``
+      # ! search_query -> the query for searching the table : ``str``
+      query = {}
+      loader = {
+        type: 'table',
+        limit: 100,
+        searchQuery: search_query,
+        loadContentCover: true
+      }
+
+      {
+        collectionId: collection_id,
+        collectionViewId: view_id,
+        query: query,
+        loader: loader
+      }
+    end
+
+    def self.add_collection_property(collection_id, args)
+      # ! payload for adding a column to the table.
+      # ! collection_id -> the collection ID : ``str``
+      # ! args -> the definition of the column : ``str``
+      {
+        id: collection_id,
+        table: 'collection',
+        path: [],
+        command: 'update',
+        args: args
+      }
+    end
+  end
+
+  def build_payload(operations, request_ids)
+    # ! properly formats the payload for Notions backend.
+    # ! operations -> an array of hashes that define the operations to perform : ``Array[Hash]``
+    # ! request_ids -> the unique IDs for the request : ``str``
+    request_id = request_ids[:request_id]
+    transaction_id = request_ids[:transaction_id]
+    space_id = request_ids[:space_id]
+    payload = {
+      requestId: request_id,
+      transactions: [
+        {
+          id: transaction_id,
+          shardId: 955_090,
+          spaceId: space_id,
+          operations: operations
+        }
+      ]
+    }
+    payload
+  end
+end