Add Note service for note.* v3 support (#515)

CHANGELOG.md

@@ -3,6 +3,14 @@
 
 ### Added
 
+- Added service `Services\Note` (Knowledge Base 2.0) with support for `note.collection.*`, `note.document.*`
+  (incl. `note.document.tree.*` and `note.document.search.*`), and `note.file.*` methods,
+  see [note REST v3](https://apidocs.bitrix24.com/api-reference/rest-v3/note/index.html) ([#515](https://github.com/bitrix24/b24phpsdk/issues/515)):
+    - `Collection`: `add`, `archive`, `delete`, `fieldGet`, `fieldList`, `get`, `list` (typed `CollectionSelectBuilder`
+      and cursor pagination via `CollectionListPagination`/`CollectionListCursor`), `update`
+    - `Document`: `add`, `archive`, `delete`, `fieldGet`, `fieldList`, `get` (typed `DocumentSelectBuilder`), `update`,
+      `treeList`/`treeFieldGet`/`treeFieldList`, `searchList`/`searchFieldGet`/`searchFieldList`
+    - `File`: `add`, `fieldGet`, `fieldList`, `get`
 - Added services `Services\Timeman\Record\Service\Record` and `Services\Timeman\RecordField\Service\RecordField`
   with support for v3 `timeman.record.*` methods,
   see [timeman REST v3](https://apidocs.bitrix24.com/api-reference/rest-v3/timeman/index.html) ([#518](https://github.com/bitrix24/b24phpsdk/issues/518)):

Makefile

@@ -625,6 +625,22 @@ test-integration-scope-timeman:
 test-integration-timeman-record:
 	docker compose run --rm php-cli $(PHPUNIT) --testsuite integration_tests_scope_timeman_record
 
+.PHONY: test-integration-scope-note
+test-integration-scope-note:
+	docker compose run --rm php-cli $(PHPUNIT) --testsuite integration_tests_scope_note
+
+.PHONY: test-integration-note-collection
+test-integration-note-collection:
+	docker compose run --rm php-cli $(PHPUNIT) --testsuite integration_tests_scope_note_collection
+
+.PHONY: test-integration-note-document
+test-integration-note-document:
+	docker compose run --rm php-cli $(PHPUNIT) --testsuite integration_tests_scope_note_document
+
+.PHONY: test-integration-note-file
+test-integration-note-file:
+	docker compose run --rm php-cli $(PHPUNIT) --testsuite integration_tests_scope_note_file
+
 .PHONY: integration_tests_sale
 integration_tests_sale:
 	docker compose run --rm php-cli $(PHPUNIT) --testsuite integration_tests_sale

phpunit.xml.dist

@@ -405,6 +405,21 @@
             <file>./tests/Integration/Services/Timeman/RecordField/Service/RecordFieldTest.php</file>
             <file>./tests/Integration/Services/Timeman/RecordField/Result/RecordFieldItemResultTest.php</file>
         </testsuite>
+        <testsuite name="integration_tests_scope_note">
+            <directory>./tests/Integration/Services/Note/</directory>
+        </testsuite>
+        <testsuite name="integration_tests_scope_note_collection">
+            <directory>./tests/Integration/Services/Note/Collection/Service/</directory>
+            <directory>./tests/Integration/Services/Note/Collection/Result/</directory>
+        </testsuite>
+        <testsuite name="integration_tests_scope_note_document">
+            <directory>./tests/Integration/Services/Note/Document/Service/</directory>
+            <directory>./tests/Integration/Services/Note/Document/Result/</directory>
+        </testsuite>
+        <testsuite name="integration_tests_scope_note_file">
+            <directory>./tests/Integration/Services/Note/File/Service/</directory>
+            <directory>./tests/Integration/Services/Note/File/Result/</directory>
+        </testsuite>
         <testsuite name="integration_tests_scope_biconnector">
             <directory>./tests/Integration/Services/Biconnector/</directory>
         </testsuite>

src/Services/Note/Collection/Result/ArchivedCollectionResult.php

@@ -0,0 +1,28 @@
+<?php
+
+/**
+ * This file is part of the bitrix24-php-sdk package.
+ *
+ * © Maksim Mesilov <mesilov.maxim@gmail.com>
+ *
+ * For the full copyright and license information, please view the MIT-LICENSE.txt
+ * file that was distributed with this source code.
+ */
+
+declare(strict_types=1);
+
+namespace Bitrix24\SDK\Services\Note\Collection\Result;
+
+use Bitrix24\SDK\Core\Exceptions\BaseException;
+use Bitrix24\SDK\Core\Result\AbstractResult;
+
+class ArchivedCollectionResult extends AbstractResult
+{
+    /**
+     * @throws BaseException
+     */
+    public function isSuccess(): bool
+    {
+        return (bool)($this->getCoreResponse()->getResponseData()->getResult()['result'] ?? false);
+    }
+}

src/Services/Note/Collection/Result/CollectionFieldItemResult.php

@@ -0,0 +1,35 @@
+<?php
+
+/**
+ * This file is part of the bitrix24-php-sdk package.
+ *
+ * © Maksim Mesilov <mesilov.maxim@gmail.com>
+ *
+ * For the full copyright and license information, please view the MIT-LICENSE.txt
+ * file that was distributed with this source code.
+ */
+
+declare(strict_types=1);
+
+namespace Bitrix24\SDK\Services\Note\Collection\Result;
+
+use Bitrix24\SDK\Core\Result\AbstractAnnotatedItem;
+
+/**
+ * Field metadata entry returned by `note.collection.field.get` / `note.collection.field.list`.
+ *
+ * @property-read string      $name
+ * @property-read string      $type
+ * @property-read string      $title
+ * @property-read string|null $description
+ * @property-read array|null  $validationRules
+ * @property-read array|null  $requiredGroups
+ * @property-read bool        $filterable
+ * @property-read bool        $sortable
+ * @property-read bool        $editable
+ * @property-read bool        $multiple
+ * @property-read string|null $elementType
+ */
+class CollectionFieldItemResult extends AbstractAnnotatedItem
+{
+}

src/Services/Note/Collection/Result/CollectionFieldResult.php

@@ -0,0 +1,28 @@
+<?php
+
+/**
+ * This file is part of the bitrix24-php-sdk package.
+ *
+ * © Maksim Mesilov <mesilov.maxim@gmail.com>
+ *
+ * For the full copyright and license information, please view the MIT-LICENSE.txt
+ * file that was distributed with this source code.
+ */
+
+declare(strict_types=1);
+
+namespace Bitrix24\SDK\Services\Note\Collection\Result;
+
+use Bitrix24\SDK\Core\Exceptions\BaseException;
+use Bitrix24\SDK\Core\Result\AbstractResult;
+
+class CollectionFieldResult extends AbstractResult
+{
+    /**
+     * @throws BaseException
+     */
+    public function field(): CollectionFieldItemResult
+    {
+        return new CollectionFieldItemResult($this->getCoreResponse()->getResponseData()->getResult()['item']);
+    }
+}

src/Services/Note/Collection/Result/CollectionFieldsResult.php

@@ -0,0 +1,34 @@
+<?php
+
+/**
+ * This file is part of the bitrix24-php-sdk package.
+ *
+ * © Maksim Mesilov <mesilov.maxim@gmail.com>
+ *
+ * For the full copyright and license information, please view the MIT-LICENSE.txt
+ * file that was distributed with this source code.
+ */
+
+declare(strict_types=1);
+
+namespace Bitrix24\SDK\Services\Note\Collection\Result;
+
+use Bitrix24\SDK\Core\Exceptions\BaseException;
+use Bitrix24\SDK\Core\Result\AbstractResult;
+
+class CollectionFieldsResult extends AbstractResult
+{
+    /**
+     * @return CollectionFieldItemResult[]
+     * @throws BaseException
+     */
+    public function getFields(): array
+    {
+        $items = [];
+        foreach ($this->getCoreResponse()->getResponseData()->getResult()['items'] as $item) {
+            $items[] = new CollectionFieldItemResult($item);
+        }
+
+        return $items;
+    }
+}

src/Services/Note/Collection/Result/CollectionItemResult.php

@@ -0,0 +1,39 @@
+<?php
+
+/**
+ * This file is part of the bitrix24-php-sdk package.
+ *
+ * © Maksim Mesilov <mesilov.maxim@gmail.com>
+ *
+ * For the full copyright and license information, please view the MIT-LICENSE.txt
+ * file that was distributed with this source code.
+ */
+
+declare(strict_types=1);
+
+namespace Bitrix24\SDK\Services\Note\Collection\Result;
+
+use Bitrix24\SDK\Attributes\OpenApiEntity;
+use Bitrix24\SDK\Core\Result\AbstractAnnotatedItem;
+use Bitrix24\SDK\Services\Note\Collection\Service\CollectionSelectBuilder;
+use Carbon\CarbonImmutable;
+
+/**
+ * A single knowledge base ("collection") returned by `note.collection.*`.
+ *
+ * @property-read int             $id
+ * @property-read string          $name
+ * @property-read int|null        $position
+ * @property-read string|null     $policyLevel
+ * @property-read int|null        $createdBy
+ * @property-read CarbonImmutable $createdAt
+ * @property-read int|null        $updatedBy
+ * @property-read CarbonImmutable $updatedAt
+ */
+#[OpenApiEntity(
+    entityKey:     'bitrix.note.collectionitemdto',
+    selectBuilder: CollectionSelectBuilder::class,
+)]
+class CollectionItemResult extends AbstractAnnotatedItem
+{
+}

src/Services/Note/Collection/Result/CollectionResult.php

@@ -0,0 +1,28 @@
+<?php
+
+/**
+ * This file is part of the bitrix24-php-sdk package.
+ *
+ * © Maksim Mesilov <mesilov.maxim@gmail.com>
+ *
+ * For the full copyright and license information, please view the MIT-LICENSE.txt
+ * file that was distributed with this source code.
+ */
+
+declare(strict_types=1);
+
+namespace Bitrix24\SDK\Services\Note\Collection\Result;
+
+use Bitrix24\SDK\Core\Exceptions\BaseException;
+use Bitrix24\SDK\Core\Result\AbstractResult;
+
+class CollectionResult extends AbstractResult
+{
+    /**
+     * @throws BaseException
+     */
+    public function collection(): CollectionItemResult
+    {
+        return new CollectionItemResult($this->getCoreResponse()->getResponseData()->getResult()['item']);
+    }
+}

src/Services/Note/Collection/Result/CollectionsResult.php

@@ -0,0 +1,45 @@
+<?php
+
+/**
+ * This file is part of the bitrix24-php-sdk package.
+ *
+ * © Maksim Mesilov <mesilov.maxim@gmail.com>
+ *
+ * For the full copyright and license information, please view the MIT-LICENSE.txt
+ * file that was distributed with this source code.
+ */
+
+declare(strict_types=1);
+
+namespace Bitrix24\SDK\Services\Note\Collection\Result;
+
+use Bitrix24\SDK\Core\Exceptions\BaseException;
+use Bitrix24\SDK\Core\Result\AbstractResult;
+use Bitrix24\SDK\Services\Note\Collection\Service\CollectionListCursor;
+
+class CollectionsResult extends AbstractResult
+{
+    /**
+     * @return CollectionItemResult[]
+     * @throws BaseException
+     */
+    public function getCollections(): array
+    {
+        $items = [];
+        foreach ($this->getCoreResponse()->getResponseData()->getResult()['items'] as $item) {
+            $items[] = new CollectionItemResult($item);
+        }
+
+        return $items;
+    }
+
+    /**
+     * @throws BaseException
+     */
+    public function getNextCursor(): ?CollectionListCursor
+    {
+        $cursor = $this->getCoreResponse()->getResponseData()->getResult()['nextCursor'] ?? null;
+
+        return $cursor === null ? null : CollectionListCursor::fromArray($cursor);
+    }
+}

src/Services/Note/Collection/Result/DeletedCollectionResult.php

@@ -0,0 +1,28 @@
+<?php
+
+/**
+ * This file is part of the bitrix24-php-sdk package.
+ *
+ * © Maksim Mesilov <mesilov.maxim@gmail.com>
+ *
+ * For the full copyright and license information, please view the MIT-LICENSE.txt
+ * file that was distributed with this source code.
+ */
+
+declare(strict_types=1);
+
+namespace Bitrix24\SDK\Services\Note\Collection\Result;
+
+use Bitrix24\SDK\Core\Exceptions\BaseException;
+use Bitrix24\SDK\Core\Result\AbstractResult;
+
+class DeletedCollectionResult extends AbstractResult
+{
+    /**
+     * @throws BaseException
+     */
+    public function isSuccess(): bool
+    {
+        return (bool)($this->getCoreResponse()->getResponseData()->getResult()['result'] ?? false);
+    }
+}