Merge pull request #6 from 5am-code/main

pull current state of main

Author: johguentner

README.md

@@ -1,8 +1,16 @@
-# Laravel Notion API
+<h1 align="center"> Laravel Notion API</h1>
+<h2 align="center"> Effortless Notion integrations with Laravel</h2>
+
+<p align="center">
+<img src="https://5amco.de/images/5am.png" width="200" height="200">
+</p>
 
 [![Latest Version on Packagist](https://img.shields.io/packagist/v/fiveam-code/laravel-notion-api.svg?style=flat-square)](https://packagist.org/packages/fiveam-code/laravel-notion-api)
 [![Total Downloads](https://img.shields.io/packagist/dt/fiveam-code/laravel-notion-api.svg?style=flat-square)](https://packagist.org/packages/fiveam-code/laravel-notion-api)
-![GitHub Actions](https://github.com/fiveam-code/laravel-notion-api/actions/workflows/main.yml/badge.svg)
+
+[comment]: <> (![GitHub Actions]&#40;https://github.com/fiveam-code/laravel-notion-api/actions/workflows/main.yml/badge.svg&#41;)
+
+This package provides a simple and crisp way to access the Notion API endpoints, query data and update existing entries.
 
 ## Installation
 
@@ -12,12 +20,68 @@ You can install the package via composer:
 composer require fiveam-code/laravel-notion-api
 ```
 
+### Authorization
+
+The Notion API requires an access token and a Notion integration, [the Notion documentation](https://developers.notion.com/docs/getting-started#before-we-begin) explains how this works. It's important to grant access to the integration within your Notion account to enable the API access.
+
+Add your Notion API token to your `.env` file:
+
+```
+NOTION_API_TOKEN="$YOUR_ACCESS_TOKEN"
+```
+
 ## Usage
 
+Head over to the [Documentation](https://5amco.de/docs) of this package.
+
+### 🔥 Code Examples to jumpstart your Notion API Project
+
+#### Basic Setup
 ```php
-// Usage description here
+use FiveamCode\LaravelNotionApi\Notion;
+use Illuminate\Support\Collection;
+use FiveamCode\LaravelNotionApi\Query\Sorting;
+use FiveamCode\LaravelNotionApi\Query\Filter;
+
+// Setup basic API connection
+$notion = new Notion();
+$notion->v1();
 ```
 
+#### Fetch Page Information
+```php
+// Returns a specific page
+$notion->pages()->find($yourPageId);
+```
+
+#### Query Database
+```php
+// Queries a specific database and returns a collection of pages (= database entries)
+$sortings = new Collection();
+$filters = new Collection();
+
+$sortings
+  ->add(Sorting::propertySort("Ordered", "ascending"));
+$sortings
+  ->add(Sorting::timestampSort("created_time", "ascending"));
+
+$filters
+  ->add(Filter::textFilter("title", ["contains" => "new"]));
+// or
+$filters
+  ->add(Filter::rawFilter("Tags", ["multi_select" => ["contains" => "great"]]));
+  
+$notion
+  ->database($yourDatabaseId)
+  ->filterBy($filters) // filters are optional
+  ->sortBy($sortings) // sorts are optional
+  ->limit(5) // limit is optional
+  ->query(); 
+```
+
+
+
+
 ### Testing
 
 ```bash
@@ -38,14 +102,13 @@ If you discover any security related issues, please email hello@dianaweb.dev ins
 
 ## Credits
 
--   [Diana Scharf](https://github.com/mechelon)
--   [Johannes Güntner](https://github.com/johguentner)
+- [Diana Scharf](https://github.com/mechelon)
+- [Johannes Güntner](https://github.com/johguentner)
 
 ## License
 
 The MIT License (MIT). Please see [License File](LICENSE.md) for more information.
 
-
-
 ## Laravel Package Boilerplate
+
 This package was generated using the [Laravel Package Boilerplate](https://laravelpackageboilerplate.com).

config/config.php

@@ -4,5 +4,5 @@
  * You can place your custom package configuration in here.
  */
 return [
-
+    'notion-api-token' => env('NOTION_API_TOKEN', '')
 ];

src/Endpoints/Block.php

@@ -0,0 +1,63 @@
+<?php
+
+namespace FiveamCode\LaravelNotionApi\Endpoints;
+
+use FiveamCode\LaravelNotionApi\Entities\Collections\BlockCollection;
+use FiveamCode\LaravelNotionApi\Exceptions\WrapperException;
+use FiveamCode\LaravelNotionApi\Notion;
+use Illuminate\Support\Collection;
+
+class Block extends Endpoint
+{
+    private string $blockId;
+
+    public function __construct(Notion $notion, string $blockId)
+    {
+        parent::__construct($notion);
+        $this->blockId = $blockId;
+    }
+
+    /**
+     * Retrieve block children
+     * url: https://api.notion.com/{version}/blocks/{block_id}/children
+     * notion-api-docs: https://developers.notion.com/reference/get-block-children
+     *
+     * @return BlockCollection
+     */
+    public function children(): Collection
+    {
+        return $this->collectChildren()->getResults();
+    }
+
+    /**
+     * Retrieve block children (as raw json-data)
+     * url: https://api.notion.com/{version}/blocks/{block_id}/children
+     * notion-api-docs: https://developers.notion.com/reference/get-block-children
+     *
+     * @return array
+     */
+    public function childrenRaw(): array
+    {
+        return $this->collectChildren()->getRawResults();
+    }
+
+    private function collectChildren(): BlockCollection
+    {
+        $response = $this->get(
+            $this->url(Endpoint::BLOCKS . "/" . $this->blockId . "/children" . "?{$this->buildPaginationQuery()}")
+        );
+
+        if (!$response->ok())
+            throw WrapperException::instance("Block not found.", ["blockId" => $this->blockId]);
+
+
+        $blockCollection = new BlockCollection($response->json());
+        return $blockCollection;
+    }
+
+    public function create(): array
+    {
+        //toDo
+        throw new \Exception("not implemented yet");
+    }
+}

src/Endpoints/Blocks.php

@@ -0,0 +1,72 @@
+<?php
+
+namespace FiveamCode\LaravelNotionApi\Endpoints;
+
+use FiveamCode\LaravelNotionApi\Entities\Collections\PageCollection;
+use Illuminate\Support\Collection;
+use FiveamCode\LaravelNotionApi\Notion;
+use FiveamCode\LaravelNotionApi\Query\Filter;
+use FiveamCode\LaravelNotionApi\Query\Sorting;
+use FiveamCode\LaravelNotionApi\Query\StartCursor;
+use FiveamCode\LaravelNotionApi\Exceptions\WrapperException;
+use Symfony\Component\VarDumper\Cloner\Data;
+
+class Database extends Endpoint
+{
+    private string $databaseId;
+
+    private Collection $filter;
+    private Collection $sorts;
+
+
+    public function __construct(string $databaseId, Notion $notion)
+    {
+        $this->databaseId = $databaseId;
+
+        $this->sorts = new Collection();
+        $this->filter = new Collection();
+
+        parent::__construct($notion);
+    }
+
+    public function query(): Collection
+    {
+        $postData = [];
+
+        if ($this->sorts->isNotEmpty())
+            $postData["sorts"] = Sorting::sortQuery($this->sorts);
+
+        if ($this->filter->isNotEmpty())
+            $postData["filter"]["or"] = Filter::filterQuery($this->filter); // TODO Compound filters!
+
+        if ($this->startCursor !== null)
+            $postData["start_cursor"] = $this->startCursor;
+
+        if ($this->pageSize !== null)
+            $postData["page_size"] = $this->pageSize;
+
+
+        $response = $this
+            ->post(
+                $this->url(Endpoint::DATABASES . "/{$this->databaseId}/query"),
+                $postData
+            )
+
+            ->json();
+
+        $pageCollection = new PageCollection($response);
+        return $pageCollection->getResults();
+    }
+
+    public function filterBy(Collection $filter)
+    {
+        $this->filter = $filter;
+        return $this;
+    }
+
+    public function sortBy(Collection $sorts)
+    {
+        $this->sorts = $sorts;
+        return $this;
+    }
+}

src/Endpoints/Database.php

@@ -3,46 +3,74 @@
 namespace FiveamCode\LaravelNotionApi\Endpoints;
 
 use FiveamCode\LaravelNotionApi\Entities\Database;
+use FiveamCode\LaravelNotionApi\Entities\Collections\DatabaseCollection;
+use FiveamCode\LaravelNotionApi\Exceptions\WrapperException;
 use FiveamCode\LaravelNotionApi\Notion;
+use FiveamCode\LaravelNotionApi\Query\StartCursor;
+use Illuminate\Support\Collection;
 
+
+/**
+ * Class Databases
+ *
+ * This endpoint is not recommended by Notion anymore.
+ * Use the search() endpoint instead.
+ *
+ * @package FiveamCode\LaravelNotionApi\Endpoints
+ */
 class Databases extends Endpoint implements EndpointInterface
 {
-    public function __construct(Notion $notion)
+
+
+    /**
+     * List databases
+     * url: https://api.notion.com/{version}/databases
+     * notion-api-docs: https://developers.notion.com/reference/get-databases
+     *
+     * @return DatabaseCollection
+     */
+    public function all(): Collection
     {
-        $this->notion = $notion;
+        return $this->collect()->getResults();
     }
 
-    /** 
-     * List databases
+    /**
+     * List databases (raw json-data)
      * url: https://api.notion.com/{version}/databases
      * notion-api-docs: https://developers.notion.com/reference/get-databases
-     * 
+     *
      * @return array
      */
-    public function all(): array
+    public function allRaw(): array
+    {
+        return $this->collect()->getRawResults();
+    }
+
+    private function collect(): DatabaseCollection
     {
-        return $this->getJson($this->url(Endpoint::DATABASES));
+        $resultData = $this->getJson($this->url(Endpoint::DATABASES) . "?{$this->buildPaginationQuery()}");
+        $databaseCollection = new DatabaseCollection($resultData);
+        return $databaseCollection;
     }
 
     /**
      * Retrieve a database
      * url: https://api.notion.com/{version}/databases/{database_id}
      * notion-api-docs: https://developers.notion.com/reference/get-database
-     * 
+     *
      * @param string $databaseId
-     * @return array
+     * @return Database
+     * @throws WrapperException
      */
     public function find(string $databaseId): Database
     {
-        $jsonArray = $this->getJson(
-            $this->url(Endpoint::DATABASES . "/" . $databaseId)
+        $response = $this->get(
+            $this->url(Endpoint::DATABASES . "/{$databaseId}")
         );
-        return new Database($jsonArray);
-    }
 
-    public function query(): array
-    {
-        //toDo
-        throw new \Exception("not implemented yet");
+        if (!$response->ok())
+            throw WrapperException::instance("Database not found.", ["databaseId" => $databaseId]);
+
+        return new Database($response->json());
     }
 }