notion 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: b3ebde6eb43b792a313801584c8043c579e9fd356427df080a14c265e28cf2db
+  data.tar.gz: 9bf0242abe3ad4c15cebbb9a1cdd65ae64b6ec76a1d8e872836a90b5c2ec9404
+SHA512:
+  metadata.gz: 2f0b872d9f1eb4f88f05e4d8e41959291dc4b86bdb0be46582d196de095f174907b78c165c35140c7bc68b41b4cd6b7b7098ae23a3502d8adecc488e9185c03a
+  data.tar.gz: 8c69f7a02a7374a69590b4b1cdb92767557efaf7f56e5fa7fe3f8450f78c19e4fa9e37b5db8c46e9aef6661dda8dfc56692baeff57912769f052e831af9ae594

data/LICENSE.md

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2020 Dan Murphy
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,196 @@
+# Unofficial Notion Client for Ruby.
+[![Build Status](https://travis-ci.com/danmurphy1217/notion-ruby.svg?branch=master)](https://travis-ci.com/danmurphy1217/notion-ruby) [![Ruby Style Guide](https://img.shields.io/badge/code_style-rubocop-brightgreen.svg)](https://github.com/rubocop-hq/rubocop)
+
+## Getting Started
+To get started using package, you'll first need to retrieve your token_v2 credentials by signing into Notion online, navigating to the developer tools, inspecting the cookies, and finding the value associated with the **token_v2** key.
+
+From here, you can instantiate the Notion Client with the following code:
+```ruby
+>>> @client = NotionAPI::Client.new("<insert_v2_token_here>")
+```
+## Retrieving a Page
+A typical starting point is the `get_page` method, which returns a Notion Page Block. The `get_page` method accepts the ID (formatted or not) or the URL of the page:
+1. URL → https://www.notion.so/danmurphy/TEST-PAGE-d2ce338f19e847f586bd17679f490e66
+2. ID → d2ce338f19e847f586bd17679f490e66
+3. Formatted ID → d2ce338f-19e8-47f5-86bd-17679f490e66
+```ruby
+>>> @client.get_page("https://www.notion.so/danmurphy/TEST-PAGE-d2ce338f19e847f586bd17679f490e66")
+>>> @client.get_page("d2ce338f19e847f586bd17679f490e66")
+>>> @client.get_page("d2ce338f-19e8-47f5-86bd-17679f490e66")
+```
+All three of these will return the same block instance:
+```ruby
+#<NotionAPI::PageBlock id="d2ce338f-19e8-47f5-86bd-17679f490e66" title="TEST" parent_id="<omitted>">
+```
+The following attributes can be read from any block class instance:
+1. `id`: the ID associated with the block.
+2. `title`: the title associated with the block.
+3. `parent_id`: the parent ID of the block.
+4. `type`: the type of the block.
+
+## Retrieving a Block within the Page
+Now that you have retrieved a Notion Page, you have full access to the blocks on that page. You can retrieve a specific block or collection view, retrieve all children IDs (array of children IDs), or retrieve all children (array of children class instances).
+
+### Get a Block
+To retrieve a specific block, you can use the `get_block` method. This method accepts the ID of the block (formatted or not), and will return the block as an instantiated class instance:
+```ruby
+@page = @client.get_page("https://www.notion.so/danmurphy/TEST-PAGE-d2ce338f19e847f586bd17679f490e66")
+@page.get_block("2cbbe0bf-34cd-409b-9162-64284b33e526")
+#<TextBlock id="2cbbe0bf-34cd-409b-9162-64284b33e526" title="TEST" parent_id="d2ce338f-19e8-47f5-86bd-17679f490e66">
+```
+Any Notion Block has access to the following methods:
+1. `title=` → change the title of a block.
+```ruby
+>>> @block = @client.get_block("2cbbe0bf-34cd-409b-9162-64284b33e526")
+>>> @block.title # get the current title...
+"TEST"
+>>> @block.title= "New Title Here" # lets update it...
+>>> @block.title
+"New Title Here"
+```
+2. `convert` → convert a block to a different type.
+```ruby
+>>> @block = @client.get_block("2cbbe0bf-34cd-409b-9162-64284b33e526")
+>>> @block.type
+"text"
+>>> @new_block = @block.convert(NotionAPI::CalloutBlock)
+>>> @new_block.type
+"callout"
+>>> @new_block # new class instance returned...
+#<NotionAPI::CalloutBlock:0x00007ffb75b19ea0 id="2cbbe0bf-34cd-409b-9162-64284b33e526" title="New Title Here" parent_id="d2ce338f-19e8-47f5-86bd-17679f490e66">
+```
+3. `duplicate`→ duplicate the current block.
+```ruby
+>>> @block = @client.get_block("2cbbe0bf-34cd-409b-9162-64284b33e526")
+>>> @block.duplicate # block is duplicated and placed directly after the current block
+>>> @block.duplicate("f13da22b-9012-4c49-ac41-6b7f97bd519e") # the duplicated block is placed after 'f13da22b-9012-4c49-ac41-6b7f97bd519e'
+```
+4. `move` → move a block to another location.
+```ruby
+>>> @block = @client.get_block("2cbbe0bf-34cd-409b-9162-64284b33e526")
+>>> @target_block = @client.get_block("c3ce468f-11e3-48g5-87be-27679g491e66")
+>>> @block.move(@target_block) # @block moved to **after** @target_block
+>>> @block.move(@target_block, "before") # @block moved to **before** @target_block
+```
+### Get a Collection View - Table
+To retrieve a collection, you use the `get_collection` method. This method is designed to work with Table collections, but the codebase is actively being updated to support others:
+```ruby
+>>> @page = @client.get_page("https://www.notion.so/danmurphy/TEST-PAGE-d2ce338f19e847f586bd17679f490e66")
+>>> @page.get_collection("34d03794-ecdd-e42d-bb76-7e4aa77b6503")
+#<NotionAPI::CollectionView:0x00007fecd8859770 @id="34d03794-ecdd-e42d-bb76-7e4aa77b6503", @title="Car Data", @parent_id="9c50a7b3-9ad7-4f2b-aa08-b3c95f1f19e7", @collection_id="5ea0fa7c-00cd-4ee0-1915-8b5c423f8f3a", @view_id="5fdb08da-0732-49dc-d0c3-2e31fccca73a">
+```
+Any Notion Block has access to the following methods:
+1. `row_ids` → retrieve the IDs associated with each row.
+```ruby
+>>> @collection = @page.get_collection("34d03794-ecdd-e42d-bb76-7e4aa77b6503")
+>>> @collection.row_ids
+ent.rb
+["785f4e24-e489-a316-50cf-b0b100c6673a", "78642d95-da23-744c-b084-46d039927bba", "96dff83c-6961-894c-39c2-c2c8bfcbfa90", "87ae8ae7-5518-fbe1-748e-eb690c707fac",..., "5a50bdd4-69c5-0708-5093-b135676e83c1", "ff9b8b89-1fed-f955-4afa-5a071198b0ee", "721fe76a-9e3c-d348-8324-994c95d77b2e"]
+```
+2. `rows` → retrieve each Row, returned as an array of TableRowInstance classes.
+```ruby
+>>> @collection = @page.get_collection("34d03794-ecdd-e42d-bb76-7e4aa77b6503")
+>>> @collection.rows
+#<NotionAPI::CollectionViewRow:0x00007ffecca82078 @id="785f4e24-e489-a316-50cf-b0b100c6673a", @parent_id="9c50a7b3-9ad7-4f2b-aa08-b3c95f1f19e7", @collection_id="5ea0fa7c-00cd-4ee0-1915-8b5c423f8f3a", @view_id="5fdb08da-0732-49dc-d0c3-2e31fccca73a">,..., #<NotionAPI::CollectionViewRow:0x00007ffecca81998 @id="fbf44f93-52ee-0e88-262a-94982ffb3fb2", @parent_id="9c50a7b3-9ad7-4f2b-aa08-b3c95f1f19e7", @collection_id="5ea0fa7c-00cd-4ee0-1915-8b5c423f8f3a", @view_id="5fdb08da-0732-49dc-d0c3-2e31fccca73a">]
+```
+3. `row("<row_id>")` → retrieve a specific row.
+```ruby
+>>> @collection = @page.get_collection("34d03794-ecdd-e42d-bb76-7e4aa77b6503")
+>>> @collection.row("f1c7077f-44a9-113d-a156-90ab6880c3e2")
+{"age"=>[9], "vin"=>["1C6SRFLT1MN591852"], "body"=>["4D Crew Cab"], "fuel"=>["Gasoline"], "make"=>["Ram"], "msrp"=>[64935], "year"=>[2021], "model"=>[1500], "price"=>[59688], "stock"=>["21R14"], "dealerid"=>["MP2964D"], "colour"=>["Bright White Clearcoat"], "engine"=>["HEMI 5.7L V8 Multi Displacement VVT"], "photos"=>["http://vehicle-photos-published.vauto.com/d0/c2/dd/8b-1307-4c67-8d31-5a301764b875/image-1.jpg"], "series"=>["Rebel"], "newused"=>["N"], "city_mpg"=>[""],...,"engine_cylinder_ct"=>[8], "engine_displacement"=>[5.7], "photos_last_modified_date"=>["11/13/2020 8:16:56 AM"]}
+```
+
+## Creating New Blocks
+To create a new block, you have a few options:
+### Create a block whose parent is the page
+If you want to create a new block whose parent ID is the **page**, call the `create` method on the PageBlock instance.
+1. `@page.create("<type_of_block", "title of block")` → create a new block at the end of the page.
+```ruby
+>>> @page = @client.get_page("https://www.notion.so/danmurphy/Notion-API-Testing-66447bc817f044bc81ed3cf4802e9b00")
+>>> @page.create(NotionAPI::TextBlock, "Hiya!")
+#<NotionAPI::TextBlock:0x00007fecd4459770 **omitted**>
+```
+2. `@page.create("<type_of_block", "title of block", "target_block_id")` → create a new block after the target block.
+```ruby
+>>> @page = @client.get_page("https://www.notion.so/danmurphy/Notion-API-Testing-66447bc817f044bc81ed3cf4802e9b00")
+>>> @page.create(NotionAPI::TextBlock, "Hiya!", "ee0a6531-44cd-439f-a68c-1bdccbebfc8a")
+#<NotionAPI::TextBlock:0x00007fecd8859770 **omitted**>
+```
+3. `@page.create("<type_of_block"), "title of block", "target_block_id", "before/after")` → create a new block after or before the target block.
+```ruby
+>>> @page = @client.get_page("https://www.notion.so/danmurphy/Notion-API-Testing-66447bc817f044bc81ed3cf4802e9b00")
+>>> @page.create(NotionAPI::TextBlock, "Hiya!", "ee0a6531-44cd-439f-a68c-1bdccbebfc8a", "before")
+#<NotionAPI::TextBlock:0x00007fecd8859880 **omitted**>
+```
+### Create a block whose parent is another block
+If you want to create a nested block whose parent ID is **another block**, call the `create` method on that block.
+1. `@block.create("<type_of_block", "title of block")` → create a new nested block whose parent ID is @block.id
+```ruby
+>>> @page = @client.get_page("https://www.notion.so/danmurphy/Notion-API-Testing-66447bc817f044bc81ed3cf4802e9b00")
+>>> @block = @page.get_block("2cbbe0bf-34cd-409b-9162-64284b33e526")
+>>> @block.create(NotionAPI::TextBlock, "Hiya!") # create a nested text block
+#<NotionAPI::TextBlock:0x00007fecd8861780 **omitted**>
+```
+2. `@block.create("<type_of_block", "title of block", "target_block")` → create a new nested block whose parent ID is @block.id and whose location is after the target block
+```ruby
+>>> @page = @client.get_page("https://www.notion.so/danmurphy/Notion-API-Testing-66447bc817f044bc81ed3cf4802e9b00")
+>>> @block = @page.get_block("2cbbe0bf-34cd-409b-9162-64284b33e526")
+>>> @block.create(NotionAPI::TextBlock, "Hiya!" "ae3d1c60-b9d1-0ac0-0fff-16d3fc8907a2") # create a nested text block after a specific child
+#<NotionAPI::TextBlock:0x00007fecd8859781 **omitted**>
+```
+3. `@block.create("<type_of_block", "title of block", "target_block", "before/after")` → reate a new nested block whose parent ID is @block.id and whose location is before the target block
+```ruby
+>>> @page = @client.get_page("https://www.notion.so/danmurphy/Notion-API-Testing-66447bc817f044bc81ed3cf4802e9b00")
+>>> @block = @page.get_block("2cbbe0bf-34cd-409b-9162-64284b33e526")
+>>> @block.create(NotionAPI::TextBlock, "Hiya!" "ae3d1c60-b9d1-0ac0-0fff-16d3fc8907a2", "before") # create a nested text block before a specific child
+#<NotionAPI::TextBlock:0x00007fecd8859781 **omitted**>
+```
+The simplest way to describe this: the parent ID of the created block is the ID of the block the `create` method is invoked on. If the `create` method is invoked on a **PageBlock**, the block is a child of that page. If the `create` method is invoked on a block within the page, the block is a child of that block.
+
+** NOTE: Notion only supports 'nesting' certain block types. If you try to nest a block that cannot be nested, it will fail. **
+## Creating New Collections
+Let's say we have the following JSON data:
+```json
+[
+  {
+    "emoji": "😀",
+    "description": "grinning face",
+    "category": "Smileys & Emotion",
+    "aliases": ["grinning"],
+    "tags": ["smile", "happy"],
+    "unicode_version": "6.1",
+    "ios_version": "6.0"
+  },
+  {
+    "emoji": "😃",
+    "description": "grinning face with big eyes",
+    "category": "Smileys & Emotion",
+    "aliases": ["smiley"],
+    "tags": ["happy", "joy", "haha"],
+    "unicode_version": "6.0",
+    "ios_version": "6.0"
+  }
+]
+```
+A new collection containing this data is created with the following code:
+```ruby
+>>> @page = @client.get_page("https://www.notion.so/danmurphy/Notion-API-Testing-66447bc817f044bc81ed3cf4802e9b00")
+>>> @page.create_collection("table", "title for table", JSON.parse(File.read("./path/to/emoji_json_data.json")))
+```
+Additionally, say you already have a Table and want to add a new row with it containing the following data:
+```ruby
+{
+    "emoji": "😉",
+    "description": "winking face",
+    "category": "Smileys & Emotion",
+    "aliases": ["wink"],
+    "tags": ["flirt"],
+    "unicode_version": "6.0",
+    "ios_version": "6.0"
+}
+```
+```ruby
+>>> @page = @client.get_page("https://www.notion.so/danmurphy/Notion-API-Testing-66447bc817f044bc81ed3cf4802e9b00")
+>>> @collection = @page.get_collection("f1664a99-165b-49cc-811c-84f37655908a")
+>>> @collection.add_row(JSON.parse(File.read("path/to/new_emoji_row.json")))
+```

data/lib/notion_api.rb

@@ -0,0 +1,5 @@
+require "notion_api/client"
+require "notion_api/core"
+require "notion_api/blocks"
+require "notion_api/utils"
+require "notion_api/markdown"

data/lib/notion_api/blocks.rb

@@ -0,0 +1,984 @@
+# frozen_string_literal: true
+
+require_relative 'core'
+require 'httparty'
+
+module NotionAPI
+  # Base Template for all blocks. Inherits core methods from the Block class defined in block.rb
+  class BlockTemplate < Core
+    include Utils
+
+    attr_reader :id, :title, :parent_id
+
+    def initialize(id, title, parent_id)
+      @id = id
+      @title = title
+      @parent_id = parent_id
+    end
+
+    def title=(new_title)
+      # ! Change the title of a block.
+      # ! new_title -> new title for the block : ``str``
+      request_id = extract_id(SecureRandom.hex(16))
+      transaction_id = extract_id(SecureRandom.hex(16))
+      space_id = extract_id(SecureRandom.hex(16))
+      update_title(new_title.to_s, request_id, transaction_id, space_id)
+      @title = new_title
+    end
+
+    def convert(block_class_to_convert_to)
+      # ! convert a block from its current type to another.
+      # ! block_class_to_convert_to -> the type of block to convert to : ``cls``
+      if type == block_class_to_convert_to.notion_type
+        # if converting to same type, skip and return self
+        self
+      else
+        # setup cookies, headers, and grab/create static vars for request
+        cookies = Core.options['cookies']
+        headers = Core.options['headers']
+        request_url = URLS[:UPDATE_BLOCK]
+
+        # set random IDs for request
+        request_id = extract_id(SecureRandom.hex(16))
+        transaction_id = extract_id(SecureRandom.hex(16))
+        space_id = extract_id(SecureRandom.hex(16))
+        request_ids = {
+          request_id: request_id,
+          transaction_id: transaction_id,
+          space_id: space_id
+        }
+
+        # build hash's that contain the operations to send to Notions backend
+        convert_type_hash = Utils::BlockComponents.convert_type(@id, block_class_to_convert_to)
+        last_edited_time_parent_hash = Utils::BlockComponents.last_edited_time(@parent_id)
+        last_edited_time_child_hash = Utils::BlockComponents.last_edited_time(@id)
+
+        operations = [
+          convert_type_hash,
+          last_edited_time_parent_hash,
+          last_edited_time_child_hash
+        ]
+
+        request_body = build_payload(operations, request_ids)
+        response = HTTParty.post(
+          request_url,
+          body: request_body.to_json,
+          cookies: cookies,
+          headers: headers
+        )
+        unless response.code == 200; raise "There was an issue completing your request. Here is the response from Notion: #{response.body}, and here is the payload that was sent: #{operations}.
+           Please try again, and if issues persist open an issue in GitHub."; end
+
+        block_class_to_convert_to.new(@id, @title, @parent_id)
+
+      end
+    end
+
+    def duplicate(target_block = nil)
+      # ! duplicate the block that this method is invoked upon.
+      # ! target_block -> the block to place the duplicated block after. Can be any valid Block ID! : ``str``
+      cookies = Core.options['cookies']
+      headers = Core.options['headers']
+      request_url = URLS[:UPDATE_BLOCK]
+
+      new_block_id = extract_id(SecureRandom.hex(16))
+      request_id = extract_id(SecureRandom.hex(16))
+      transaction_id = extract_id(SecureRandom.hex(16))
+      space_id = extract_id(SecureRandom.hex(16))
+
+      root_children = children_ids(@id)
+      sub_children = []
+      root_children.each { |root_id| sub_children.push(children_ids(root_id)) }
+
+      request_ids = {
+        request_id: request_id,
+        transaction_id: transaction_id,
+        space_id: space_id
+      }
+      body = {
+        pageId: @id,
+        chunkNumber: 0,
+        limit: 100,
+        verticalColumns: false
+      }
+
+      user_notion_id = get_notion_id(body)
+
+      block = target_block ? get(target_block) : self # allows dev to place block anywhere!
+
+      duplicate_hash = Utils::BlockComponents.duplicate(type, @title, block.id, new_block_id, user_notion_id, root_children)
+      set_parent_alive_hash = Utils::BlockComponents.set_parent_to_alive(block.parent_id, new_block_id)
+      block_location_hash = Utils::BlockComponents.block_location_add(block.parent_id, block.id, new_block_id, target_block, 'listAfter')
+      last_edited_time_parent_hash = Utils::BlockComponents.last_edited_time(block.parent_id)
+      last_edited_time_child_hash = Utils::BlockComponents.last_edited_time(block.id)
+
+      operations = [
+        duplicate_hash,
+        set_parent_alive_hash,
+        block_location_hash,
+        last_edited_time_parent_hash,
+        last_edited_time_child_hash
+      ]
+
+      request_body = build_payload(operations, request_ids)
+      response = HTTParty.post(
+        request_url,
+        body: request_body.to_json,
+        cookies: cookies,
+        headers: headers
+      )
+      unless response.code == 200; raise "There was an issue completing your request. Here is the response from Notion: #{response.body}, and here is the payload that was sent: #{operations}.
+         Please try again, and if issues persist open an issue in GitHub."; end
+
+      class_to_return = NotionAPI.const_get(Classes.select { |cls| NotionAPI.const_get(cls).notion_type == type }.join.to_s)
+      class_to_return.new(new_block_id, @title, block.parent_id)
+    end
+
+    def move(target_block, position = 'after')
+      # ! move the block to a new location.
+      # ! target_block -> the targetted block to move to. : ``str``
+      # ! position -> where the block should be listed, in positions relative to the target_block [before, after, top-child, last-child]
+      positions_hash = {
+        'after' => 'listAfter',
+        'before' => 'listBefore'
+      }
+
+      unless positions_hash.keys.include?(position); raise ArgumentError, "Invalid position. You said: #{position}, valid options are: #{positions_hash.keys.join(', ')}"; end
+
+      position_command = positions_hash[position]
+      cookies = Core.options['cookies']
+      headers = Core.options['headers']
+      request_url = URLS[:UPDATE_BLOCK]
+
+      request_id = extract_id(SecureRandom.hex(16))
+      transaction_id = extract_id(SecureRandom.hex(16))
+      space_id = extract_id(SecureRandom.hex(16))
+
+      request_ids = {
+        request_id: request_id,
+        transaction_id: transaction_id,
+        space_id: space_id
+      }
+
+      check_parents = (@parent_id == target_block.parent_id)
+      set_block_dead_hash = Utils::BlockComponents.set_block_to_dead(@id) # kill the block this method is invoked on...
+      block_location_remove_hash = Utils::BlockComponents.block_location_remove(@parent_id, @id) # remove the block this method is invoked on...
+      parent_location_hash = Utils::BlockComponents.parent_location_add(check_parents ? @parent_id : target_block.parent_id, @id) # set parent location to alive
+      block_location_add_hash = Utils::BlockComponents.block_location_add(check_parents ? @parent_id : target_block.parent_id, @id, target_block.id, position_command)
+      last_edited_time_parent_hash = Utils::BlockComponents.last_edited_time(@parent_id)
+
+      if check_parents
+        last_edited_time_child_hash = Utils::BlockComponents.last_edited_time(@id)
+        operations = [
+          set_block_dead_hash,
+          block_location_remove_hash,
+          parent_location_hash,
+          block_location_add_hash,
+          last_edited_time_parent_hash,
+          last_edited_time_child_hash
+        ]
+      else
+        last_edited_time_new_parent_hash = Utils::BlockComponents.last_edited_time(target_block.parent_id)
+        last_edited_time_child_hash = Utils::BlockComponents.last_edited_time(@id)
+        @parent_id = target_block.parent_id
+        operations = [
+          set_block_dead_hash,
+          block_location_remove_hash,
+          parent_location_hash,
+          block_location_add_hash,
+          last_edited_time_parent_hash,
+          last_edited_time_new_parent_hash,
+          last_edited_time_child_hash
+        ]
+      end
+      request_body = build_payload(operations, request_ids)
+      response = HTTParty.post(
+        request_url,
+        body: request_body.to_json,
+        cookies: cookies,
+        headers: headers
+      )
+      unless response.code == 200; raise "There was an issue completing your request. Here is the response from Notion: #{response.body}, and here is the payload that was sent: #{operations}.
+         Please try again, and if issues persist open an issue in GitHub."; end
+
+      self
+    end
+
+    def create(block_type, block_title, target = nil, position = 'after')
+      # ! create a new block
+      # ! block_type -> the type of block to create : ``cls``
+      # ! block_title -> the title of the new block : ``str``
+      # ! target -> the block_id that the new block should be placed after. ``str`` 
+      # ! position -> 'after' or 'before'
+      positions_hash = {
+        'after' => 'listAfter',
+        'before' => 'listBefore'
+      }
+      unless positions_hash.keys.include?(position); raise "Invalid position. You said: #{position}, valid options are: #{positions_hash.keys.join(', ')}"; end
+
+      position_command = positions_hash[position]
+
+      cookies = Core.options['cookies']
+      headers = Core.options['headers']
+
+      new_block_id = extract_id(SecureRandom.hex(16))
+      request_id = extract_id(SecureRandom.hex(16))
+      transaction_id = extract_id(SecureRandom.hex(16))
+      space_id = extract_id(SecureRandom.hex(16))
+
+      request_ids = {
+        request_id: request_id,
+        transaction_id: transaction_id,
+        space_id: space_id
+      }
+
+      create_hash = Utils::BlockComponents.create(new_block_id, block_type.notion_type)
+      set_parent_alive_hash = Utils::BlockComponents.set_parent_to_alive(@id, new_block_id)
+      block_location_hash = Utils::BlockComponents.block_location_add(@id, @id, new_block_id, target, position_command)
+      last_edited_time_parent_hash = Utils::BlockComponents.last_edited_time(@id)
+      last_edited_time_child_hash = Utils::BlockComponents.last_edited_time(@id)
+      title_hash = Utils::BlockComponents.title(new_block_id, block_title)
+
+      operations = [
+        create_hash,
+        set_parent_alive_hash,
+        block_location_hash,
+        last_edited_time_parent_hash,
+        last_edited_time_child_hash,
+        title_hash
+      ]
+
+      request_url = URLS[:UPDATE_BLOCK]
+      request_body = build_payload(operations, request_ids)
+      response = HTTParty.post(
+        request_url,
+        body: request_body.to_json,
+        cookies: cookies,
+        headers: headers
+      )
+      unless response.code == 200; raise "There was an issue completing your request. Here is the response from Notion: #{response.body}, and here is the payload that was sent: #{operations}.
+         Please try again, and if issues persist open an issue in GitHub."; end
+
+      block_type.new(new_block_id, block_title, @id)
+    end
+
+    private
+
+    def get(url_or_id)
+      # ! retrieve a Notion 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_type = extract_type(clean_id, jsonified_record_response)
+      block_parent_id = extract_parent_id(clean_id, jsonified_record_response)
+
+      if block_type.nil?
+        {}
+      else
+        block_class = NotionAPI.const_get(BLOCK_TYPES[block_type].to_s)
+        if block_class == NotionAPI::CollectionView
+          block_collection_id = extract_collection_id(clean_id, jsonified_record_response)
+          block_view_id = extract_view_ids(clean_id, jsonified_record_response)
+          collection_title = extract_collection_title(clean_id, block_collection_id, jsonified_record_response)
+          block_class.new(clean_id, collection_title, block_parent_id, block_collection_id, block_view_id.join)
+        else
+          block_title = extract_title(clean_id, jsonified_record_response)
+          block_class.new(clean_id, block_title, block_parent_id)
+        end
+      end
+    end
+
+    def update_title(new_title, request_id, transaction_id, space_id)
+      # ! Helper method for sending POST request to change title of block.
+      # ! new_title -> new title for the block : ``str``
+      # ! request_id -> the unique ID for the request key. Generated using SecureRandom : ``str``
+      # ! transaction_id -> the unique ID for the transaction key. Generated using SecureRandom: ``str``
+      # ! transaction_id -> the unique ID for the space key. Generated using SecureRandom: ``str``
+      # setup cookies, headers, and grab/create static vars for request
+      cookies = Core.options['cookies']
+      headers = Core.options['headers']
+      request_url = URLS[:UPDATE_BLOCK]
+
+      # set unique IDs for request
+      request_ids = {
+        request_id: request_id,
+        transaction_id: transaction_id,
+        space_id: space_id
+      }
+
+      # build and set operations to send to Notion
+      title_hash = Utils::BlockComponents.title(@id, new_title)
+      last_edited_time_parent_hash = Utils::BlockComponents.last_edited_time(@parent_id)
+      last_edited_time_child_hash = Utils::BlockComponents.last_edited_time(@id)
+      operations = [
+        title_hash,
+        last_edited_time_parent_hash,
+        last_edited_time_child_hash
+      ]
+
+      request_body = build_payload(operations, request_ids) # defined in utils.rb
+
+      response = HTTParty.post(
+        request_url,
+        body: request_body.to_json,
+        cookies: cookies,
+        headers: headers
+      )
+      response.body
+    end
+  end
+
+  # divider block: ---------
+  class DividerBlock < BlockTemplate
+    @notion_type = 'divider'
+    @type = 'divider'
+
+    def type
+      NotionAPI::DividerBlock.notion_type
+    end
+
+    class << self
+      attr_reader :notion_type, :type
+    end
+  end
+
+  # To-Do block: best for checklists and tracking to-dos.
+  class TodoBlock < BlockTemplate
+    @notion_type = 'to_do'
+    @type = 'to_do'
+
+    def type
+      NotionAPI::TodoBlock.notion_type
+    end
+
+    class << self
+      attr_reader :notion_type, :type
+    end
+
+    def checked=(checked_value)
+      # ! change the checked property of the Todo Block.
+      # ! checked_value -> boolean value used to determine whether the block should be checked [yes] or not [no] : ``str``
+      # set static variables for request
+      cookies = Core.options['cookies']
+      headers = Core.options['headers']
+      request_url = URLS[:UPDATE_BLOCK]
+
+      # set unique values for request
+      request_id = extract_id(SecureRandom.hex(16))
+      transaction_id = extract_id(SecureRandom.hex(16))
+      space_id = extract_id(SecureRandom.hex(16))
+      request_ids = {
+        request_id: request_id,
+        transaction_id: transaction_id,
+        space_id: space_id
+      }
+
+      if %w[yes no].include?(checked_value.downcase)
+        checked_hash = Utils::BlockComponents.checked_todo(@id, checked_value.downcase)
+        last_edited_time_parent_hash = Utils::BlockComponents.last_edited_time(@parent_id)
+        last_edited_time_child_hash = Utils::BlockComponents.last_edited_time(@id)
+
+        operations = [
+          checked_hash,
+          last_edited_time_parent_hash,
+          last_edited_time_child_hash
+        ]
+        request_body = build_payload(operations, request_ids)
+        response = HTTParty.post(
+          request_url,
+          body: request_body.to_json,
+          cookies: cookies,
+          headers: headers
+        )
+        unless response.code == 200; raise "There was an issue completing your request. Here is the response from Notion: #{response.body}, and here is the payload that was sent: #{operations}.
+           Please try again, and if issues persist open an issue in GitHub."; end
+
+        true
+      else
+        false
+      end
+    end
+  end
+
+  # Code block: used to store code, should be assigned a coding language.
+  class CodeBlock < BlockTemplate
+    @notion_type = 'code'
+    @type = 'code'
+
+    def type
+      NotionAPI::CodeBlock.notion_type
+    end
+
+    class << self
+      attr_reader :notion_type, :type
+    end
+  end
+
+  # Header block: H1
+  class HeaderBlock < BlockTemplate
+    @notion_type = 'header'
+    @type = 'header'
+
+    def type
+      NotionAPI::HeaderBlock.notion_type
+    end
+
+    class << self
+      attr_reader :notion_type, :type
+    end
+  end
+
+  # SubHeader Block: H2
+  class SubHeaderBlock < BlockTemplate
+    @notion_type = 'sub_header'
+    @type = 'sub_header'
+
+    def type
+      NotionAPI::SubHeaderBlock.notion_type
+    end
+
+    class << self
+      attr_reader :notion_type, :type
+    end
+  end
+
+  # Sub-Sub Header Block: H3
+  class SubSubHeaderBlock < BlockTemplate
+    @notion_type = 'sub_sub_header'
+    @type = 'sub_sub_header'
+
+    def type
+      NotionAPI::SubSubHeaderBlock.notion_type
+    end
+
+    class << self
+      attr_reader :notion_type, :type
+    end
+  end
+
+  # Page Block, entrypoint for the application
+  class PageBlock < BlockTemplate
+    @notion_type = 'page'
+    @type = 'page'
+
+    def type
+      NotionAPI::PageBlock.notion_type
+    end
+
+    class << self
+      attr_reader :notion_type, :type
+    end
+
+    def get_block(url_or_id)
+      # ! retrieve a Notion Block and return its instantiated class object.
+      # ! url_or_id -> the block ID or URL : ``str``
+      get(url_or_id)
+    end
+
+    def get_collection(url_or_id)
+      # ! retrieve a Notion Collection 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_parent_id = extract_parent_id(clean_id, jsonified_record_response)
+      block_collection_id = extract_collection_id(clean_id, jsonified_record_response)
+      block_view_id = extract_view_ids(clean_id, jsonified_record_response).join
+      block_title = extract_collection_title(clean_id, block_collection_id, jsonified_record_response)
+
+      CollectionView.new(clean_id, block_title, block_parent_id, block_collection_id, block_view_id)
+    end
+
+    def create_collection(_collection_type, collection_title, data)
+      # ! create a Notion Collection View and return its instantiated class object.
+      # ! _collection_type -> the type of collection to create : ``str``
+      # ! collection_title -> the title of the collection view : ``str``
+      # ! data -> JSON data to add to the table : ``str``
+
+      unless %w[table].include?(_collection_type) ; raise ArgumentError, "That collection type is not yet supported. Try: \"table\"."; end
+      cookies = Core.options['cookies']
+      headers = Core.options['headers']
+
+      new_block_id = extract_id(SecureRandom.hex(16))
+      parent_id = extract_id(SecureRandom.hex(16))
+      collection_id = extract_id(SecureRandom.hex(16))
+      view_id = extract_id(SecureRandom.hex(16))
+
+      children = []
+      alive_blocks = []
+      data.each do |_row|
+        child = extract_id(SecureRandom.hex(16))
+        children.push(child)
+        alive_blocks.push(Utils::CollectionViewComponents.set_collection_blocks_alive(child, collection_id))
+      end
+
+      request_id = extract_id(SecureRandom.hex(16))
+      transaction_id = extract_id(SecureRandom.hex(16))
+      space_id = extract_id(SecureRandom.hex(16))
+
+      request_ids = {
+        request_id: request_id,
+        transaction_id: transaction_id,
+        space_id: space_id
+      }
+
+      create_collection_view = Utils::CollectionViewComponents.create_collection_view(new_block_id, collection_id, view_id)
+      configure_view = Utils::CollectionViewComponents.set_view_config(new_block_id, view_id, children)
+      configure_columns = Utils::CollectionViewComponents.set_collection_columns(collection_id, new_block_id, data)
+      set_parent_alive_hash = Utils::BlockComponents.set_parent_to_alive(@id, new_block_id)
+      add_block_hash = Utils::BlockComponents.block_location_add(@id, @id, new_block_id, nil, 'listAfter')
+      new_block_edited_time = Utils::BlockComponents.last_edited_time(new_block_id)
+      collection_title_hash = Utils::CollectionViewComponents.set_collection_title(collection_title, collection_id)
+
+      operations = [
+        create_collection_view,
+        configure_view,
+        configure_columns,
+        set_parent_alive_hash,
+        add_block_hash,
+        new_block_edited_time,
+        collection_title_hash
+      ]
+      operations << alive_blocks
+      all_ops = operations.flatten
+      data.each_with_index do |row, i|
+        child = children[i]
+        row.keys.each_with_index do |col_name, j|
+          child_component = Utils::CollectionViewComponents.insert_data(child, j.zero? ? 'title' : col_name, row[col_name])
+          all_ops.push(child_component)
+        end
+      end
+
+      request_url = URLS[:UPDATE_BLOCK]
+      request_body = build_payload(all_ops, request_ids)
+      response = HTTParty.post(
+        request_url,
+        body: request_body.to_json,
+        cookies: cookies,
+        headers: headers
+      )
+
+      unless response.code == 200; raise "There was an issue completing your request. Here is the response from Notion: #{response.body}, and here is the payload that was sent: #{operations}.
+         Please try again, and if issues persist open an issue in GitHub."; end
+
+      CollectionView.new(new_block_id, collection_title, parent_id, collection_id, view_id)
+    end
+  end
+
+  # Toggle block: best for storing children blocks
+  class ToggleBlock < BlockTemplate
+    @notion_type = 'toggle'
+    @type = 'toggle'
+
+    def type
+      NotionAPI::ToggleBlock.notion_type
+    end
+
+    class << self
+      attr_reader :notion_type, :type
+    end
+  end
+
+  # Bullet list block: best for an unordered list
+  class BulletedBlock < BlockTemplate
+    @notion_type = 'bulleted_list'
+    @type = 'bulleted_list'
+
+    def type
+      NotionAPI::BulletedBlock.notion_type
+    end
+
+    class << self
+      attr_reader :notion_type, :type
+    end
+  end
+
+  # Numbered list Block: best for an ordered list
+  class NumberedBlock < BlockTemplate
+    @notion_type = 'numbered_list'
+    @type = 'numbered_list'
+
+    def type
+      NotionAPI::NumberedBlock.notion_type
+    end
+
+    class << self
+      attr_reader :notion_type, :type
+    end
+  end
+
+  # best for memorable information
+  class QuoteBlock < BlockTemplate
+    @notion_type = 'quote'
+    @type = 'quote'
+
+    def type
+      NotionAPI::QuoteBlock.notion_type
+    end
+
+    class << self
+      attr_reader :notion_type, :type
+    end
+  end
+
+  # same as quote... works similarly to page block
+  class CalloutBlock < BlockTemplate
+    @notion_type = 'callout'
+    @type = 'callout'
+
+    def type
+      NotionAPI::CalloutBlock.notion_type
+    end
+
+    class << self
+      attr_reader :notion_type, :type
+    end
+  end
+
+  # simiilar to code block but for mathematical functions.
+  class LatexBlock < BlockTemplate
+    @notion_type = 'equation'
+    @type = 'equation'
+
+    def type
+      NotionAPI::LatexBlock.notion_type
+    end
+
+    class << self
+      attr_reader :notion_type, :type
+    end
+  end
+
+  # good for just about anything (-:
+  class TextBlock < BlockTemplate
+    @notion_type = 'text'
+    @type = 'text'
+
+    def type
+      NotionAPI::TextBlock.notion_type
+    end
+
+    class << self
+      attr_reader :notion_type, :type
+    end
+  end
+
+  # good for visual information
+  class ImageBlock < BlockTemplate
+    @notion_type = 'image'
+    @type = 'image'
+
+    def type
+      NotionAPI::ImageBlock.notion_type
+    end
+
+    class << self
+      attr_reader :notion_type, :type
+    end
+  end
+
+  # maps out the headers - sub-headers - sub-sub-headers on the page
+  class TableOfContentsBlock < BlockTemplate
+    @notion_type = 'table_of_contents'
+    @type = 'table_of_contents'
+
+    def type
+      NotionAPI::TableOfContentsBlock.notion_type
+    end
+
+    class << self
+      attr_reader :notion_type, :type
+    end
+  end
+
+  # no use case for this yet.
+  class ColumnListBlock < BlockTemplate
+    @notion_type = 'column_list'
+    @type = 'column_list'
+
+    def type
+      NotionAPI::ColumnListBlock.notion_type
+    end
+
+    class << self
+      attr_reader :notion_type, :type
+    end
+  end
+
+  # no use case for this yet.
+  class ColumnBlock < BlockTemplate
+    @notion_type = 'column'
+    @type = 'column'
+
+    def type
+      NotionAPI::ColumnBlock.notion_type
+    end
+
+    class << self
+      attr_reader :notion_type, :type
+    end
+  end
+end
+
+module NotionAPI
+  # collection views such as tables and timelines.
+  class CollectionView < Core
+    attr_reader :id, :title, :parent_id, :collection_id, :view_id
+
+    @notion_type = 'collection_view'
+    @type = 'collection_view'
+
+    def type
+      NotionAPI::CollectionView.notion_type
+    end
+
+    class << self
+      attr_reader :notion_type, :type
+    end
+
+    def initialize(id, title, parent_id, collection_id, view_id)
+      @id = id
+      @title = title
+      @parent_id = parent_id
+      @collection_id = collection_id
+      @view_id = view_id
+    end
+
+    def add_row(data)
+      # ! add new row to Collection View table.
+      # ! data -> data to add to table : ``hash``
+
+      cookies = Core.options['cookies']
+      headers = Core.options['headers']
+
+      request_id = extract_id(SecureRandom.hex(16))
+      transaction_id = extract_id(SecureRandom.hex(16))
+      space_id = extract_id(SecureRandom.hex(16))
+      new_block_id = extract_id(SecureRandom.hex(16))
+      schema = extract_collection_schema(@collection_id, @view_id)
+      keys = schema.keys
+      col_map = {}
+      keys.map { |key| col_map[schema[key]['name']]  = key }
+
+      request_ids = {
+        request_id: request_id,
+        transaction_id: transaction_id,
+        space_id: space_id
+      }
+
+      instantiate_row = Utils::CollectionViewComponents.add_new_row(new_block_id)
+      set_block_alive = Utils::CollectionViewComponents.set_collection_blocks_alive(new_block_id, @collection_id)
+      new_block_edited_time = Utils::BlockComponents.last_edited_time(new_block_id)
+      parent_edited_time = Utils::BlockComponents.last_edited_time(@parent_id)
+
+      operations = [
+        instantiate_row,
+        set_block_alive,
+        new_block_edited_time,
+        parent_edited_time
+      ]
+
+      data.keys.each_with_index do |col_name, j|
+        child_component = Utils::CollectionViewComponents.insert_data(new_block_id, j.zero? ? 'title' : col_map[col_name], data[col_name])
+        operations.push(child_component)
+      end
+
+      request_url = URLS[:UPDATE_BLOCK]
+      request_body = build_payload(operations, request_ids)
+      response = HTTParty.post(
+        request_url,
+        body: request_body.to_json,
+        cookies: cookies,
+        headers: headers
+      )
+
+      unless response.code == 200; raise "There was an issue completing your request. Here is the response from Notion: #{response.body}, and here is the payload that was sent: #{operations}.
+         Please try again, and if issues persist open an issue in GitHub."; end
+
+         NotionAPI::CollectionViewRow.new(new_block_id, @parent_id, @collection_id, @view_id)
+    end
+
+    def add_property(name, type)
+      # ! add a property (column) to the table.
+      # ! name -> name of the property : ``str``
+      # ! type -> type of the property : ``str``
+      cookies = Core.options['cookies']
+      headers = Core.options['headers']
+
+      request_id = extract_id(SecureRandom.hex(16))
+      transaction_id = extract_id(SecureRandom.hex(16))
+      space_id = extract_id(SecureRandom.hex(16))
+
+      request_ids = {
+        request_id: request_id,
+        transaction_id: transaction_id,
+        space_id: space_id
+      }
+
+      # create updated schema
+      schema = extract_collection_schema(@collection_id, @view_id)
+      schema[name] = {
+        name: name,
+        type: type
+      }
+      new_schema = {
+        schema: schema
+      }
+
+      add_collection_property = Utils::CollectionViewComponents.add_collection_property(@collection_id, new_schema)
+
+      operations = [
+        add_collection_property
+      ]
+
+      request_url = URLS[:UPDATE_BLOCK]
+      request_body = build_payload(operations, request_ids)
+      response = HTTParty.post(
+        request_url,
+        body: request_body.to_json,
+        cookies: cookies,
+        headers: headers
+      )
+      unless response.code == 200; raise "There was an issue completing your request. Here is the response from Notion: #{response.body}, and here is the payload that was sent: #{operations}.
+         Please try again, and if issues persist open an issue in GitHub."; end
+
+      true
+    end
+
+    def row(row_id)
+      # ! retrieve a row from a CollectionView Table.
+      # ! row_id -> the ID for the row to retrieve: ``str``
+      clean_id = extract_id(row_id)
+
+      request_body = {
+        pageId: clean_id,
+        chunkNumber: 0,
+        limit: 100,
+        verticalColumns: false
+      }
+      jsonified_record_response = get_all_block_info(clean_id, request_body)
+      schema = extract_collection_schema(@collection_id, @view_id)
+      keys = schema.keys
+      column_names = keys.map { |key| schema[key]['name'] }
+      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
+      row_jsonified_response = jsonified_record_response['block'][clean_id]['value']['properties']
+      row_data = {}
+      keys.each_with_index { |key, idx| row_data[column_names[idx]] = row_jsonified_response[key] ? row_jsonified_response[key].flatten : [] }
+      row_data
+    end
+
+    def row_ids
+      # ! retrieve all Collection View table rows.
+      clean_id = extract_id(@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
+
+      jsonified_record_response['collection_view'][@view_id]['value']['page_sort']
+    end
+
+    def rows
+      # ! returns all rows as instantiated class instances.
+      row_id_array = row_ids
+      parent_id = @parent_id
+      collection_id = @collection_id
+      view_id = @view_id
+
+      row_id_array.map { |row_id| NotionAPI::CollectionViewRow.new(row_id, parent_id, collection_id, view_id) }
+    end
+
+    private
+
+    def extract_collection_schema(collection_id, view_id)
+      # ! retrieve the collection scehma. Useful for 'building' the backbone for a table.
+      # ! collection_id -> the collection ID : ``str``
+      # ! view_id -> the view ID : ``str``
+      cookies = Core.options['cookies']
+      headers = Core.options['headers']
+
+      query_collection_hash = Utils::CollectionViewComponents.query_collection(collection_id, view_id, '')
+
+      request_url = URLS[:GET_COLLECTION]
+      response = HTTParty.post(
+        request_url,
+        body: query_collection_hash.to_json,
+        cookies: cookies,
+        headers: headers
+      )
+      response['recordMap']['collection'][collection_id]['value']['schema']
+    end
+  end
+  # Class for each row in a Collection View Table.
+  class CollectionViewRow < Core
+    @notion_type = 'table_row'
+    @type = 'table_row'
+
+    def type
+      NotionAPI::CollectionViewRow.notion_type
+    end
+
+    class << self
+      attr_reader :notion_type, :type, :parent_id
+    end
+
+    attr_reader :parent_id, :id
+    def initialize(id, parent_id, collection_id, view_id)
+      @id = id
+      @parent_id = parent_id
+      @collection_id = collection_id
+      @view_id = view_id
+    end
+  end
+end
+
+# gather a list of all the classes defined here...
+Classes = NotionAPI.constants.select { |c| NotionAPI.const_get(c).is_a? Class and c.to_s != 'BlockTemplate' and c.to_s != 'Core' and c.to_s !='Client' }
+notion_types = []
+Classes.each { |cls| notion_types.push(NotionAPI.const_get(cls).notion_type) }
+BLOCK_TYPES = notion_types.zip(Classes).to_h