feat(search): search pages and databases

Closes #62

CHANGELOG.md

@@ -10,7 +10,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Added
 - Support unknown blocks and page/database properties. Pages and databases with unsuported resources will be loaded without errors. (#173)
-- Add page and database properties collection with typed getters. (#179)
+- Page and database properties collection with typed getters. (#179)
+- Search pages and databases.
 
 ## [1.4.1]
 

docs/.vitepress/config.ts

@@ -112,6 +112,14 @@ export default defineConfig({
                     { text: 'Introduction', link: '/comments/' },
                 ],
             },
+            {
+                text: 'Search',
+                collapsible: true,
+                collapsed: true,
+                items: [
+                    { text: 'Introduction', link: '/search/' },
+                ],
+            },
             {
                 text: 'Advanced',
                 collapsible: true,

docs/search/index.md

@@ -0,0 +1,46 @@
+# Search
+
+## Introduction
+
+Searches all parent or child pages and databases that have been shared with an
+integration.
+
+Returns all pages or databases, excluding duplicated linked databases, that have
+titles that include the query param. If no query param is provided, then the
+response contains all pages or databases that have been shared with the
+integration.
+
+::: warning
+If you want to search a specific individual database, rather than across all
+databases, then [query a database](../how-to/query-database.md) instead.
+:::
+
+## Searching
+
+```php
+use Notion\Search\Query;
+
+$query = Query::title("Example"); // Search by page/database title...
+$query = Query::all();            // ... or search everything
+
+$result = $notion->search()->search($query);
+
+$result->hasMore;    // bool
+$result->nextCursor; // CursorId when hasMore is true
+$result->results;    // array of Page and/or Database objects
+```
+
+## Query options
+
+```php
+use Notion\Search\Query;
+
+$query = Query::title("Example");                                // Page or database title
+$query = $query->filterByPages();                                // Return only pages
+$query = $query->filterByDatabases();                            // Return only databases
+$query = $query->sortByLastEditedTime(SortDirection::Ascending); // Results order
+
+// Pagination
+$query = $query->changePageSize(10);
+$query = $query->changeNextCursor("70d73991-7e06-43d9-ad3c-3711213f1235")
+```

psalm.xml

@@ -2,9 +2,9 @@
     errorLevel="1"
     resolveFromConfigFile="true"
     memoizeMethodCallResults="true"
-    findUnusedPsalmSuppress="true"
-    findUnusedCode="true"
-    findUnusedBaselineEntry="true"
+    findUnusedPsalmSuppress="false"
+    findUnusedCode="false"
+    findUnusedBaselineEntry="false"
     xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
     xmlns="https://getpsalm.org/schema/config"
     xsi:schemaLocation="https://getpsalm.org/schema/config vendor/vimeo/psalm/config.xsd"

src/Notion.php

@@ -6,6 +6,7 @@
 use Notion\Comments\Client as CommentsClient;
 use Notion\Databases\Client as DatabasesClient;
 use Notion\Pages\Client as PagesClient;
+use Notion\Search\Client as SearchClient;
 use Notion\Users\Client as UsersClient;
 use Psr\Http\Client\ClientInterface;
 use Psr\Http\Message\RequestFactoryInterface;
@@ -69,4 +70,9 @@ public function comments(): CommentsClient
     {
         return new CommentsClient($this->configuration);
     }
+
+    public function search(): SearchClient
+    {
+        return new SearchClient($this->configuration);
+    }
 }

src/Pages/Page.php

@@ -19,6 +19,7 @@
  * @psalm-import-type PageParentJson from PageParent
  *
  * @psalm-type PageJson = array{
+ *      object: "page",
  *      id: string,
  *      created_time: string,
  *      last_edited_time: string,
@@ -108,6 +109,7 @@ public static function fromArray(array $array): self
     public function toArray(): array
     {
         return [
+            "object"           => "page",
             "id"               => $this->id,
             "created_time"     => $this->createdTime->format(Date::FORMAT),
             "last_edited_time" => $this->lastEditedTime->format(Date::FORMAT),

src/Search/Client.php

@@ -0,0 +1,33 @@
+<?php
+
+namespace Notion\Search;
+
+use Notion\Configuration;
+use Notion\Infrastructure\Http;
+
+/** @psalm-import-type ResultJson from \Notion\Search\Result */
+class Client
+{
+    /**
+     * @internal Use `\Notion\Notion::search()` instead
+     */
+    public function __construct(
+        private readonly Configuration $config,
+    ) {
+    }
+
+    public function search(Query $query): Result
+    {
+        $data = json_encode($query->toArray(), JSON_PRETTY_PRINT);
+        $url = "https://api.notion.com/v1/search";
+        $request = Http::createRequest($url, $this->config)
+            ->withMethod("POST")
+            ->withHeader("Content-Type", "application/json");
+        $request->getBody()->write($data);
+
+        /** @psalm-var ResultJson $body */
+        $body = Http::sendRequest($request, $this->config);
+
+        return Result::fromArray($body);
+    }
+}

src/Search/Filter.php

@@ -0,0 +1,38 @@
+<?php
+
+namespace Notion\Search;
+
+/** @psalm-immutable */
+class Filter
+{
+    private function __construct(
+        public readonly FilterValue $value,
+        public readonly FilterProperty $property,
+    ) {
+    }
+
+    /** @psalm-mutation-free */
+    public static function byPages(): self
+    {
+        return new self(FilterValue::Page, FilterProperty::Object);
+    }
+
+    /** @psalm-mutation-free */
+    public static function byDatabases(): self
+    {
+        return new self(FilterValue::Database, FilterProperty::Object);
+    }
+
+    /**
+     * @internal
+     *
+     * @return array{ value: "page"|"database", property: "object" }
+     */
+    public function toArray(): array
+    {
+        return [
+            "value" => $this->value->value,
+            "property" => $this->property->value,
+        ];
+    }
+}

src/Search/FilterProperty.php

@@ -0,0 +1,8 @@
+<?php
+
+namespace Notion\Search;
+
+enum FilterProperty: string
+{
+    case Object = "object";
+}

src/Search/FilterValue.php

@@ -0,0 +1,9 @@
+<?php
+
+namespace Notion\Search;
+
+enum FilterValue: string
+{
+    case Page = "page";
+    case Database = "database";
+}

src/Search/Query.php

@@ -0,0 +1,121 @@
+<?php
+
+namespace Notion\Search;
+
+/** @psalm-immutable */
+class Query
+{
+    private function __construct(
+        public readonly string|null $query = null,
+        public readonly Filter|null $filter = null,
+        public readonly Sort|null $sort = null,
+        public readonly string|null $startCursor = null,
+        public readonly int|null $pageSize = null,
+    ) {
+    }
+
+    public static function all(): self
+    {
+        return new self();
+    }
+
+    public static function title(string $query): self
+    {
+        return new self($query);
+    }
+
+    public function filterByPages(): self
+    {
+        return new self(
+            $this->query,
+            Filter::byPages(),
+            $this->sort,
+            $this->startCursor,
+            $this->pageSize,
+        );
+    }
+
+    public function filterByDatabases(): self
+    {
+        return new self(
+            $this->query,
+            Filter::byDatabases(),
+            $this->sort,
+            $this->startCursor,
+            $this->pageSize,
+        );
+    }
+
+    public function sortByLastEditedTime(SortDirection $direction): self
+    {
+        $sort = Sort::create()->byLastEditedTime();
+
+        return new self(
+            $this->query,
+            $this->filter,
+            $direction === SortDirection::Ascending ? $sort->ascending() : $sort->descending(),
+            $this->startCursor,
+            $this->pageSize,
+        );
+    }
+
+    public function changeStartCursor(string $startCursor): self
+    {
+        return new self(
+            $this->query,
+            $this->filter,
+            $this->sort,
+            $startCursor,
+            $this->pageSize,
+        );
+    }
+
+    public function changePageSize(int $pageSize): self
+    {
+        return new self(
+            $this->query,
+            $this->filter,
+            $this->sort,
+            $this->startCursor,
+            $pageSize,
+        );
+    }
+
+    /**
+     * @internal
+     *
+     * @return array{
+     *      query?: string,
+     *      filter?: array{ value: string, property: string },
+     *      sort?: array{ direction: string, timestamp: string },
+     *      start_cursor?: string,
+     *      page_size?: int
+     * }
+     */
+    public function toArray(): array
+    {
+        $array = [];
+
+        if ($this->query !== null) {
+            $array["query"] = $this->query;
+        }
+
+        if ($this->filter !== null) {
+            $array["filter"] = $this->filter->toArray();
+        }
+
+        if ($this->sort !== null) {
+            $array["sort"] = $this->sort->toArray();
+        }
+
+        if ($this->startCursor !== null) {
+            $array["start_cursor"] = $this->startCursor;
+        }
+
+        if ($this->pageSize !== null) {
+            $array["page_size"] = $this->pageSize;
+        }
+
+        return $array;
+    }
+}

src/Search/Result.php

@@ -0,0 +1,56 @@
+<?php
+
+namespace Notion\Search;
+
+use Notion\Databases\Database;
+use Notion\Pages\Page;
+
+/**
+ * @psalm-immutable
+ *
+ * @psalm-import-type PageJson from \Notion\Pages\Page
+ * @psalm-import-type DatabaseJson from \Notion\Databases\Database
+ *
+ * @psalm-type ResultJson = array{
+ *      object: string,
+ *      results: list{PageJson, DatabaseJson},
+ *      next_cursor: string|null,
+ *      has_more: bool
+ * }
+ */
+class Result
+{
+    /** @param list{Page, Database} $results */
+    private function __construct(
+        public readonly array $results,
+        public readonly string|null $nextCursor,
+        public readonly bool $hasMore,
+    ) {
+    }
+
+    /**
+     * @psalm-param ResultJson $array
+     */
+    public static function fromArray(array $array): self
+    {
+        $results = [];
+        foreach ($array["results"] as $result) {
+            if ($result["object"] === "page") {
+                /** @psalm-var PageJson $result */
+                $results[] = Page::fromArray($result);
+            }
+
+            if ($result["object"] === "database") {
+                /** @psalm-var DatabaseJson $result */
+                $results[] = Database::fromArray($result);
+            }
+        }
+
+        /** @psalm-var list{Page, Database} $results */
+        return new self(
+            $results,
+            $array["next_cursor"],
+            $array["has_more"],
+        );
+    }
+}