add the ability to resolve users and parents

- some entities have parents or expose user-ids, without additional information
- by resolving these within the "endpoint" (not a real notion enpoint) ``Resolve::class``, the additional information can be easily obtained

Author: johguentner

src/Endpoints/Resolve.php

@@ -0,0 +1,69 @@
+<?php
+
+namespace FiveamCode\LaravelNotionApi\Endpoints;
+
+use FiveamCode\LaravelNotionApi\Entities\Blocks\Block;
+use FiveamCode\LaravelNotionApi\Entities\Collections\CommentCollection;
+use FiveamCode\LaravelNotionApi\Entities\Comment;
+use FiveamCode\LaravelNotionApi\Entities\Database;
+use FiveamCode\LaravelNotionApi\Entities\NotionParent;
+use FiveamCode\LaravelNotionApi\Entities\Page;
+use FiveamCode\LaravelNotionApi\Entities\Properties\Relation;
+use FiveamCode\LaravelNotionApi\Entities\User;
+use FiveamCode\LaravelNotionApi\Exceptions\HandlingException;
+use FiveamCode\LaravelNotionApi\Exceptions\NotionException;
+use FiveamCode\LaravelNotionApi\Notion;
+
+/**
+ * Class Resolve.
+ */
+class Resolve extends Endpoint
+{
+    /**
+     * Block constructor.
+     *
+     * @param  Notion  $notion
+     *
+     * @throws HandlingException
+     * @throws \FiveamCode\LaravelNotionApi\Exceptions\LaravelNotionAPIException
+     */
+    public function __construct(Notion $notion)
+    {
+        parent::__construct($notion);
+    }
+
+    /**
+     * @param  User  $user
+     * 
+     * @return User
+     * @throws HandlingException
+     * @throws NotionException
+     */
+    public function user(User $user): User
+    {
+        return $this->notion->users()->find($user->getId());
+    }
+
+    /**
+     * @param  NotionParent  $parent
+     * 
+     * @return Page|Database|Block
+     * @throws HandlingException
+     * @throws NotionException
+     */
+    public function parent(NotionParent $parent): Page|Database|Block
+    {
+        switch ($parent->getObjectType()) {
+            case 'page_id':
+                return $this->notion->pages()->find($parent->getId());
+            case 'database_id':
+                return $this->notion->databases()->find($parent->getId());
+            case 'block_id':
+                return $this->notion->block($parent->getId())->retrieve();
+            case 'workspace_id':
+                throw new HandlingException('A Notion Workspace cannot be resolved by the Notion API.');
+            default:
+                throw new HandlingException('Unknown parent type while resolving the notion parent');
+        }
+    }
+}

src/Entities/NotionParent.php

@@ -0,0 +1,68 @@
+<?php
+
+namespace FiveamCode\LaravelNotionApi\Entities;
+
+use FiveamCode\LaravelNotionApi\Exceptions\HandlingException;
+
+/**
+ * Class NotionParent.
+ */
+class NotionParent extends Entity
+{
+    /**
+     * @param  array  $responseData
+     *
+     * @throws HandlingException
+     * @throws \FiveamCode\LaravelNotionApi\Exceptions\NotionException
+     */
+    protected function setResponseData(array $responseData): void
+    {
+        parent::setResponseData($responseData);
+        if (
+            $responseData['object'] !== 'page_id'
+            && $responseData['object'] !== 'database_id'
+            && $responseData['object'] !== 'workspace_id'
+            && $responseData['object'] !== 'block_id'
+        ) {
+            throw HandlingException::instance('invalid json-array: the given object is not a valid parent');
+        }
+        $this->fillFromRaw();
+    }
+
+    private function fillFromRaw(): void
+    {
+        parent::fillEntityBase();
+    }
+
+    /**
+     * @return bool
+     */
+    public function isBlock(): bool
+    {
+        return $this->getObjectType() === 'block_id';
+    }
+
+    /**
+     * @return bool
+     */
+    public function isPage(): bool
+    {
+        return $this->getObjectType() === 'page_id';
+    }
+
+    /**
+     * @return bool
+     */
+    public function isDatabase(): bool
+    {
+        return $this->getObjectType() === 'database_id';
+    }
+
+    /**
+     * @return bool
+     */
+    public function isWorkspace(): bool
+    {
+        return $this->getObjectType() === 'workspace_id';
+    }
+}

src/Notion.php

@@ -8,6 +8,7 @@
 use FiveamCode\LaravelNotionApi\Endpoints\Databases;
 use FiveamCode\LaravelNotionApi\Endpoints\Endpoint;
 use FiveamCode\LaravelNotionApi\Endpoints\Pages;
+use FiveamCode\LaravelNotionApi\Endpoints\Resolve;
 use FiveamCode\LaravelNotionApi\Endpoints\Search;
 use FiveamCode\LaravelNotionApi\Endpoints\Users;
 use FiveamCode\LaravelNotionApi\Exceptions\HandlingException;
@@ -196,6 +197,11 @@ public function comments(): Comments
         return new Comments($this);
     }
 
+    public function resolve(): Resolve
+    {
+        return new Resolve($this);
+    }
+
     /**
      * @return string
      */
@@ -221,7 +227,7 @@ public function getConnection(): ?PendingRequest
      */
     public function checkValidVersion(string $version): void
     {
-        if (! $this->validVersions->contains($version)) {
+        if (!$this->validVersions->contains($version)) {
             throw HandlingException::instance('Invalid version for Notion-API endpoint', ['invalidVersion' => $version]);
         }
     }

src/Traits/HasParent.php

@@ -2,6 +2,7 @@
 
 namespace FiveamCode\LaravelNotionApi\Traits;
 
+use FiveamCode\LaravelNotionApi\Entities\NotionParent;
 use Illuminate\Support\Arr;
 
 /**
@@ -54,4 +55,15 @@ public function getParentType(): string
     {
         return $this->parentType;
     }
+
+    /**
+     * @return NotionParent
+     */
+    public function getParent()
+    {
+        return new NotionParent([
+            'id' => $this->getParentId(),
+            'object' => $this->getParentType()
+        ]);
+    }
 }