add the ability to resolve users and parents

.gitignore

@@ -3,4 +3,5 @@ vendor
 .phpunit.result.cache
 coverage/
 .phpunit.cache/
-.env*
+.env*
+coverage-report

composer.json

@@ -49,10 +49,13 @@
     },
     "scripts": {
         "test": "vendor/bin/pest",
-        "test-coverage": "vendor/bin/pest --coverage-html coverage"
+        "test-coverage": "phpdbg -qrr ./vendor/bin/pest --coverage-html ./coverage-report"
     },
     "config": {
-        "sort-packages": true
+        "sort-packages": true,
+        "allow-plugins": {
+            "pestphp/pest-plugin": true
+        }
     },
     "extra": {
         "laravel": {

src/Endpoints/Comments.php

@@ -38,14 +38,15 @@ public function __construct(Notion $notion)
     }
 
     /**
-     * Retrieve a list of comments
-     * url: https://api.notion.com/{version}/comments?block_id=* [get]
-     * notion-api-docs: https://developers.notion.com/reference/retrieve-a-comment.
+     * Retrieve a list of comments.
+     *
+     * @url https://api.notion.com/{version}/comments?block_id=* [get]
+     *
+     * @reference https://developers.notion.com/reference/retrieve-a-comment.
      *
      * @param  string  $blockId
      * @return CommentCollection
      *
-     * @throws HandlingException
      * @throws NotionException
      */
     public function ofBlock(string $blockId): CommentCollection
@@ -88,14 +89,15 @@ public function onPage(string $pageId): self
     }
 
     /**
-     * Create a comment
-     * url: https://api.notion.com/{version}/comments [post]
-     * notion-api-docs: https://developers.notion.com/reference/create-a-comment.
+     * Create a comment.
+     *
+     * @url https://api.notion.com/{version}/comments [post]
+     *
+     * @reference https://developers.notion.com/reference/create-a-comment.
      *
      * @param  CommentEntity  $comment
      * @return CommentEntity
      *
-     * @throws HandlingException
      * @throws NotionException
      */
     public function create($comment): CommentEntity

src/Endpoints/Resolve.php

@@ -0,0 +1,120 @@
+<?php
+
+namespace FiveamCode\LaravelNotionApi\Endpoints;
+
+use FiveamCode\LaravelNotionApi\Entities\Blocks\Block;
+use FiveamCode\LaravelNotionApi\Entities\Database;
+use FiveamCode\LaravelNotionApi\Entities\Entity;
+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;
+use FiveamCode\LaravelNotionApi\Traits\HasParent;
+use Illuminate\Support\Collection;
+
+/**
+ * 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);
+    }
+
+    /**
+     * Resolve User.
+     *
+     * @param  User  $user
+     * @return User
+     *
+     * @throws HandlingException
+     * @throws NotionException
+     */
+    public function user(User $user): User
+    {
+        return $this->notion->users()->find($user->getId());
+    }
+
+    /**
+     * Resolve Parent of an entity.
+     *
+     * @param  Entity  $entity
+     * @return Page|Database|Block
+     *
+     * @throws HandlingException
+     * @throws NotionException
+     */
+    public function parentOf(Entity $entity)
+    {
+        if (! in_array(HasParent::class, class_uses_recursive(get_class($entity)))) {
+            throw new HandlingException("The given entity '{$entity->getObjectType()}' does not have a parent.");
+        }
+
+        return $this->parent($entity->getParent());
+    }
+
+    /**
+     * Resolve Parent.
+     *
+     * @param  NotionParent  $parent
+     * @return Page|Database|Block
+     *
+     * @throws HandlingException
+     * @throws NotionException
+     */
+    public function parent(NotionParent $parent): Page|Database|Block|NotionParent
+    {
+        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':
+                return $parent;
+                // 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');
+        }
+    }
+
+    /**
+     * Resolve Relations.
+     *
+     * @param  Relation  $relation
+     * @return Collection<Page>
+     *
+     * @throws HandlingException
+     * @throws NotionException
+     */
+    public function relations(Relation $relation, bool $onlyTitles = false): Collection
+    {
+        $pages = collect();
+        $relationIds = $relation->getRelation()->map(function ($o) {
+            return $o['id'];
+        });
+
+        foreach ($relationIds as $relationId) {
+            if ($onlyTitles) {
+                $pages->add($this->notion->pages()->find($relationId)->getTitle());
+            } else {
+                $pages->add($this->notion->pages()->find($relationId));
+            }
+        }
+
+        return $pages;
+    }
+}

src/Entities/NotionParent.php

@@ -0,0 +1,70 @@
+<?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'
+            && $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::fillEssentials();
+    }
+
+    /**
+     * @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';
+    }
+}

src/Macros/PestHttpRecorder.php

@@ -4,6 +4,7 @@
 
 use GuzzleHttp\Client;
 use Illuminate\Http\Client\Request;
+use Illuminate\Support\Arr;
 use Illuminate\Support\Facades\File;
 use Illuminate\Support\Facades\Http;
 use Illuminate\Support\Str;
@@ -37,6 +38,8 @@ class HttpRecorder
 
     private $usePrettyJson = true;
 
+    private $requestNames = [];
+
     public function storeIn($directory)
     {
         $this->snapshotDirectory = $directory;
@@ -51,21 +54,32 @@ public function minifyJson()
         return $this;
     }
 
+    public function nameForNextRequest($name)
+    {
+        array_push($this->requestNames, $name);
+    }
+
     public function handle(Request $request)
     {
         $forceRecording = in_array('--force-recording', $_SERVER['argv']);
 
         $urlInfo = parse_url($request->url());
+        $payload = null;
 
         // create specific filename for storing snapshots
+        $header = $request->headers();
         $method = Str::lower($request->method());
         $name = Str::slug(Str::replace('/', '-', $urlInfo['path']));
-        $query = Str::slug(Str::replace('&', '_', Str::replace('=', '-', $urlInfo['query'])));
+        $payload = ($method === 'get') ? ($urlInfo['query'] ?? null) : $request->body();
+        $queryName = array_pop($this->requestNames) ?? hash('adler32', $payload);
 
-        $fileName = "{$method}_{$name}_{$query}.json";
+        $fileName = "{$method}_{$name}_{$queryName}.json";
         $directoryPath = "tests/{$this->snapshotDirectory}";
         $filePath = "{$directoryPath}/{$fileName}";
 
+        // filter out Notion API Token Header
+        $header = Arr::except($header, ['Authorization']);
+
         if ($forceRecording || ! File::exists($filePath)) {
             File::makeDirectory($directoryPath, 0744, true, true);
 
@@ -77,7 +91,10 @@ public function handle(Request $request)
             ]);
 
             $recordedResponse = [
+                'header' => $header,
+                'method' => $method,
                 'status' => $response->getStatusCode(),
+                'payload' => ($method === 'get') ? $payload : json_decode($payload, true),
                 'data' => json_decode($response->getBody()->getContents(), true),
             ];
 

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
      */

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(),
+        ]);
+    }
 }