Merge branch 'dev' into feature/block-creation

Author: johguentner

src/Endpoints/Block.php

@@ -32,6 +32,25 @@ public function __construct(Notion $notion, string $blockId)
         $this->blockId = $blockId;
     }
 
+    /**
+     * Retrieve a block
+     * url: https://api.notion.com/{version}/blocks/{block_id}
+     * notion-api-docs: https://developers.notion.com/reference/retrieve-a-block
+     *
+     * @param string $blockId
+     * @return BlockEntity
+     * @throws HandlingException
+     * @throws NotionException
+     */
+    public function retrieve(): BlockEntity {
+
+        $response = $this->get(
+            $this->url(Endpoint::BLOCKS . '/' . $this->blockId)
+        );
+
+        return BlockEntity::fromResponse($response->json());
+    }
+
     /**
      * Retrieve block children
      * url: https://api.notion.com/{version}/blocks/{block_id}/children [get]

src/Exceptions/NotionException.php

@@ -3,6 +3,7 @@
 namespace FiveamCode\LaravelNotionApi\Exceptions;
 
 use Illuminate\Http\Client\Response;
+use Throwable;
 
 /**
  * Class NotionException
@@ -33,8 +34,22 @@ public static function instance(string $message, array $payload = []): NotionExc
      */
     public static function fromResponse(Response $response): NotionException
     {
+        $responseBody = json_decode($response->getBody()->getContents(), true);
+
+        $errorCode = $errorMessage = "";
+        if (array_key_exists("code", $responseBody)) {
+            $errorCode = "({$responseBody["code"]})";
+        }
+
+        if (array_key_exists("code", $responseBody)) {
+            $errorMessage = "({$responseBody["message"]})";
+        }
+
+        $message = "{$response->getReasonPhrase()}: {$errorCode} {$errorMessage}";
+
         return new NotionException(
-            $response->getReasonPhrase(), 0,
+            $message,
+            0,
             $response->toException()
         );
     }

tests/EndpointBlocksTest.php

@@ -2,6 +2,7 @@
 
 namespace FiveamCode\LaravelNotionApi\Tests;
 
+use FiveamCode\LaravelNotionApi\Entities\PropertyItems\RichText;
 use Notion;
 use Illuminate\Support\Facades\Http;
 use FiveamCode\LaravelNotionApi\Entities\Blocks\Block;
@@ -59,7 +60,7 @@ public function it_returns_block_collection_with_children()
         Http::fake([
             'https://api.notion.com/v1/blocks/b55c9c91-384d-452b-81db-d1ef79372b76/children*'
             => Http::response(
-                json_decode(file_get_contents('tests/stubs/endpoints/blocks/response_specific_200.json'), true),
+                json_decode(file_get_contents('tests/stubs/endpoints/blocks/response_specific_block_children_200.json'), true),
                 200,
                 ['Headers']
             )
@@ -299,4 +300,24 @@ public function it_returns_parent_block_in_which_new_blocks_have_been_successful
         $parentBlock = Notion::block('1d719dd1-563b-4387-b74f-20da92b827fb')->append([$paragraph, $bulletedListItem, $headingOne, $headingTwo, $headingThree, $numberedListItem, $toDo, $toggle, $embed, $image, $video, $pdf]);
         $this->assertInstanceOf(Block::class, $parentBlock);
     }
+
+    /** @test */
+    public function it_retrieves_a_single_block()
+    {
+        // successful /v1/blocks/BLOCK_DOES_EXIST
+        Http::fake([
+            'https://api.notion.com/v1/blocks/a6f8ebe8d5df4ffab543bcd54d1c3bad'
+            => Http::response(
+                json_decode(file_get_contents('tests/stubs/endpoints/blocks/response_specific_block_200.json'), true),
+                200,
+                ['Headers']
+            )
+        ]);
+
+        $block = \Notion::block("a6f8ebe8d5df4ffab543bcd54d1c3bad")->retrieve();
+
+        $this->assertInstanceOf(Block::class, $block);
+        $this->assertInstanceOf(Paragraph::class, $block);
+    }
+
 }

tests/NotionExceptionTest.php

@@ -0,0 +1,34 @@
+<?php
+
+namespace FiveamCode\LaravelNotionApi\Tests;
+
+use FiveamCode\LaravelNotionApi\Exceptions\NotionException;
+use Notion;
+use Illuminate\Support\Facades\Http;
+
+/**
+ * Class HandlingExceptionTest
+ * @package FiveamCode\LaravelNotionApi\Tests
+ */
+class NotionExceptionTest extends NotionApiTest
+{
+
+    /** @test */
+    public function it_throws_a_notion_exception_with_detailed_message_from_response()
+    {
+
+        Http::fake([
+            'https://api.notion.com/v1/blocks/d092140ce4e549bf9915fb8ad43d1699d/children*'
+            => Http::response(
+                json_decode(file_get_contents("tests/stubs/endpoints/blocks/response_children_invalid_uuid_400.json"), true),
+                400,
+                ['Headers']
+            )
+        ]);
+
+        $this->expectException(NotionException::class);
+        $this->expectExceptionMessage("Bad Request: (validation_error) (path failed validation: path.id should be a valid uuid, instead was");
+
+        \Notion::block("d092140ce4e549bf9915fb8ad43d1699d")->children()->asCollection();
+    }
+}

tests/stubs/endpoints/blocks/response_children_invalid_uuid_400.json

@@ -0,0 +1,6 @@
+{
+  "object": "error",
+  "status": 400,
+  "code": "validation_error",
+  "message": "path failed validation: path.id should be a valid uuid, instead was `\"d092140ce4e549bf9915fb8ad43d1699d\"`."
+}

tests/stubs/endpoints/blocks/response_specific_block_200.json

@@ -1,8 +1,30 @@
 {
-    "object": "block",
-    "id": "1d719dd1-563b-4387-b74f-20da92b827fb",
-    "created_time": "2021-07-17T16:51:00.000Z",
-    "last_edited_time": "2021-07-17T16:54:00.000Z",
-    "has_children": false,
-    "type": "page"
+  "object": "block",
+  "id": "a6f8ebe8-d5df-4ffa-b543-bcd54d1c3bad",
+  "created_time": "2021-05-17T13:51:00.000Z",
+  "last_edited_time": "2021-06-10T17:40:00.000Z",
+  "has_children": false,
+  "archived": false,
+  "type": "paragraph",
+  "paragraph": {
+    "text": [
+      {
+        "type": "text",
+        "text": {
+          "content": "C:\\xampp\\php",
+          "link": null
+        },
+        "annotations": {
+          "bold": false,
+          "italic": false,
+          "strikethrough": false,
+          "underline": false,
+          "code": false,
+          "color": "default"
+        },
+        "plain_text": "C:\\xampp\\php",
+        "href": null
+      }
+    ]
+  }
 }