Merge pull request #696 from bitrix24/feature/687-note-collection-v3

Add REST v3 note.collection move, restore and unarchive (#687)

Author: mesilov

CHANGELOG.md

@@ -4,6 +4,7 @@
 
 ### Added
 - Added REST v3 `note.file.list` with typed file results, attachment dates, and opaque cursor pagination; added dedicated file field metadata access while preserving existing methods ([#688](https://github.com/bitrix24/b24phpsdk/issues/688))
+- Added REST v3 `note.collection.move`, `note.collection.restore` and `note.collection.unarchive` to the Note `Collection` service; added `accessLevel`, `state` (`CollectionState` enum), `isArchived` and `markdownDescription` to `CollectionItemResult`, matching selectors to `CollectionSelectBuilder`, `editableGroups` to `CollectionFieldItemResult` and `getFieldsDescription()` to `CollectionFieldsResult` ([#687](https://github.com/bitrix24/b24phpsdk/issues/687))
 - Added an eager `Core\Credentials\RenewedAuthToken` compatibility alias preserving legacy constructors, signatures and serialized tokens ([#117](https://github.com/bitrix24/b24phpsdk/issues/117))
 - Added non-interactive legacy API coverage reporting with `--show`, `--scope` and `--format=json` options ([#410](https://github.com/bitrix24/b24phpsdk/issues/410))
 
@@ -19,6 +20,7 @@
 - Corrected `InstantMessenger::VALUE_TYPE` conversion and PHPDoc to use `InstantMessengerValueType` ([#156](https://github.com/bitrix24/b24phpsdk/issues/156))
 - Distinguished response decoding failures with `ResponseDecodingException` while preserving sanitized diagnostics and excluding unsafe exception chains ([#667](https://github.com/bitrix24/b24phpsdk/issues/667))
 - Reused core pagination for Task, Sale Order and BasketItem batches, preserving requested sorting, nested result references, filters and limits ([#363](https://github.com/bitrix24/b24phpsdk/issues/363))
+- Fixed dead REST v3 documentation links in the Note `Collection` service metadata; they now point to `https://apidocs.bitrix24.com/api-reference/note/collection/` ([#687](https://github.com/bitrix24/b24phpsdk/issues/687))
 
 ## 3.7.0
 

docs/open-api/openapi.json

@@ -27,6 +27,7 @@
  * @property-read bool        $filterable
  * @property-read bool        $sortable
  * @property-read bool        $editable
+ * @property-read array|null  $editableGroups
  * @property-read bool        $multiple
  * @property-read string|null $elementType
  */

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

@@ -14,10 +14,33 @@
 namespace Bitrix24\SDK\Services\Note\Collection\Result;
 
 use Bitrix24\SDK\Core\Exceptions\BaseException;
+use Bitrix24\SDK\Core\Exceptions\LogicException;
 use Bitrix24\SDK\Core\Result\AbstractResult;
 
 class CollectionFieldsResult extends AbstractResult
 {
+    /**
+     * Include name when selecting metadata fields so descriptors can be indexed.
+     *
+     * @return array<string, array<string, mixed>>
+     * @throws BaseException
+     * @throws LogicException
+     */
+    public function getFieldsDescription(): array
+    {
+        $fields = [];
+        foreach ($this->getCoreResponse()->getResponseData()->getResult()['items'] as $field) {
+            $name = $field['name'] ?? null;
+            if (!is_string($name) || $name === '') {
+                throw new LogicException('Collection field metadata must contain a nonempty string name.');
+            }
+
+            $fields[$name] = $field;
+        }
+
+        return $fields;
+    }
+
     /**
      * @return CollectionFieldItemResult[]
      * @throws BaseException

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

@@ -25,10 +25,14 @@
  * @property-read string          $name
  * @property-read int|null        $position
  * @property-read string|null     $policyLevel
+ * @property-read string|null     $accessLevel
+ * @property-read CollectionState $state
+ * @property-read bool            $isArchived
  * @property-read int|null        $createdBy
  * @property-read CarbonImmutable $createdAt
  * @property-read int|null        $updatedBy
  * @property-read CarbonImmutable $updatedAt
+ * @property-read string|null     $markdownDescription
  */
 #[OpenApiEntity(
     entityKey:     'bitrix.note.collectionitemdto',

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

@@ -0,0 +1,24 @@
+<?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;
+
+/**
+ * Lifecycle state of a knowledge base (collection).
+ */
+enum CollectionState: string
+{
+    case live = 'live';
+    case archived = 'archived';
+    case trashed = 'trashed';
+}

src/Services/Note/Collection/Result/CollectionState.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 RestoredCollectionResult extends AbstractResult
+{
+    /**
+     * @throws BaseException
+     */
+    public function isSuccess(): bool
+    {
+        return (bool)($this->getCoreResponse()->getResponseData()->getResult()['result'] ?? false);
+    }
+}

src/Services/Note/Collection/Result/RestoredCollectionResult.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 UnarchivedCollectionResult extends AbstractResult
+{
+    /**
+     * @throws BaseException
+     */
+    public function isSuccess(): bool
+    {
+        return (bool)($this->getCoreResponse()->getResponseData()->getResult()['result'] ?? false);
+    }
+}

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

@@ -28,21 +28,23 @@
 use Bitrix24\SDK\Services\Note\Collection\Result\CollectionResult;
 use Bitrix24\SDK\Services\Note\Collection\Result\CollectionsResult;
 use Bitrix24\SDK\Services\Note\Collection\Result\DeletedCollectionResult;
+use Bitrix24\SDK\Services\Note\Collection\Result\RestoredCollectionResult;
+use Bitrix24\SDK\Services\Note\Collection\Result\UnarchivedCollectionResult;
 
 #[ApiServiceMetadata(new Scope(['note']))]
 class Collection extends AbstractService
 {
     /**
      * Creates a new knowledge base (collection).
      *
-     * @link https://apidocs.bitrix24.com/api-reference/rest-v3/note/collection/note-collection-add.html
+     * @link https://apidocs.bitrix24.com/api-reference/note/collection/note-collection-add.html
      *
      * @throws BaseException
      * @throws TransportException
      */
     #[ApiEndpointMetadata(
         'note.collection.add',
-        'https://apidocs.bitrix24.com/api-reference/rest-v3/note/collection/note-collection-add.html',
+        'https://apidocs.bitrix24.com/api-reference/note/collection/note-collection-add.html',
         'Creates a new knowledge base.',
         ApiVersion::v3
     )]
@@ -68,14 +70,14 @@ public function add(string $name, ?int $position = null): CollectionResult
     /**
      * Archives a knowledge base.
      *
-     * @link https://apidocs.bitrix24.com/api-reference/rest-v3/note/collection/note-collection-archive.html
+     * @link https://apidocs.bitrix24.com/api-reference/note/collection/note-collection-archive.html
      *
      * @throws BaseException
      * @throws TransportException
      */
     #[ApiEndpointMetadata(
         'note.collection.archive',
-        'https://apidocs.bitrix24.com/api-reference/rest-v3/note/collection/note-collection-archive.html',
+        'https://apidocs.bitrix24.com/api-reference/note/collection/note-collection-archive.html',
         'Archives a knowledge base.',
         ApiVersion::v3
     )]
@@ -89,15 +91,15 @@ public function archive(int $id): ArchivedCollectionResult
     /**
      * Deletes a knowledge base by id or by filter.
      *
-     * @link https://apidocs.bitrix24.com/api-reference/rest-v3/note/collection/note-collection-delete.html
+     * @link https://apidocs.bitrix24.com/api-reference/note/collection/note-collection-delete.html
      *
      * @param array|FilterBuilderInterface $filter Filter conditions (REST v3 format)
      * @throws BaseException
      * @throws TransportException
      */
     #[ApiEndpointMetadata(
         'note.collection.delete',
-        'https://apidocs.bitrix24.com/api-reference/rest-v3/note/collection/note-collection-delete.html',
+        'https://apidocs.bitrix24.com/api-reference/note/collection/note-collection-delete.html',
         'Deletes a knowledge base.',
         ApiVersion::v3
     )]
@@ -125,15 +127,15 @@ public function delete(?int $id = null, array|FilterBuilderInterface $filter = [
     /**
      * Returns the metadata of a single `note.collection` field.
      *
-     * @link https://apidocs.bitrix24.com/api-reference/rest-v3/note/collection/note-collection-field-get.html
+     * @link https://apidocs.bitrix24.com/api-reference/note/collection/note-collection-field-get.html
      *
      * @param array<int,string> $select
      * @throws BaseException
      * @throws TransportException
      */
     #[ApiEndpointMetadata(
         'note.collection.field.get',
-        'https://apidocs.bitrix24.com/api-reference/rest-v3/note/collection/note-collection-field-get.html',
+        'https://apidocs.bitrix24.com/api-reference/note/collection/note-collection-field-get.html',
         'Returns metadata of a single collection field.',
         ApiVersion::v3
     )]
@@ -157,15 +159,15 @@ public function fieldGet(string $name, array $select = []): CollectionFieldResul
     /**
      * Returns the metadata of all `note.collection` fields.
      *
-     * @link https://apidocs.bitrix24.com/api-reference/rest-v3/note/collection/note-collection-field-list.html
+     * @link https://apidocs.bitrix24.com/api-reference/note/collection/note-collection-field-list.html
      *
      * @param array<int,string> $select
      * @throws BaseException
      * @throws TransportException
      */
     #[ApiEndpointMetadata(
         'note.collection.field.list',
-        'https://apidocs.bitrix24.com/api-reference/rest-v3/note/collection/note-collection-field-list.html',
+        'https://apidocs.bitrix24.com/api-reference/note/collection/note-collection-field-list.html',
         'Returns metadata of all collection fields.',
         ApiVersion::v3
     )]
@@ -183,15 +185,15 @@ public function fieldList(array $select = []): CollectionFieldsResult
     /**
      * Returns a single knowledge base by id.
      *
-     * @link https://apidocs.bitrix24.com/api-reference/rest-v3/note/collection/note-collection-get.html
+     * @link https://apidocs.bitrix24.com/api-reference/note/collection/note-collection-get.html
      *
      * @param array<int,string>|CollectionSelectBuilder $select
      * @throws BaseException
      * @throws TransportException
      */
     #[ApiEndpointMetadata(
         'note.collection.get',
-        'https://apidocs.bitrix24.com/api-reference/rest-v3/note/collection/note-collection-get.html',
+        'https://apidocs.bitrix24.com/api-reference/note/collection/note-collection-get.html',
         'Returns a single knowledge base by id.',
         ApiVersion::v3
     )]
@@ -219,14 +221,14 @@ public function get(int $id, array|CollectionSelectBuilder $select = []): Collec
     /**
      * Returns a cursor-paginated list of knowledge bases available to the user.
      *
-     * @link https://apidocs.bitrix24.com/api-reference/rest-v3/note/collection/note-collection-list.html
+     * @link https://apidocs.bitrix24.com/api-reference/note/collection/note-collection-list.html
      *
      * @throws BaseException
      * @throws TransportException
      */
     #[ApiEndpointMetadata(
         'note.collection.list',
-        'https://apidocs.bitrix24.com/api-reference/rest-v3/note/collection/note-collection-list.html',
+        'https://apidocs.bitrix24.com/api-reference/note/collection/note-collection-list.html',
         'Returns a list of knowledge bases available to the user.',
         ApiVersion::v3
     )]
@@ -241,10 +243,91 @@ public function list(?CollectionListPagination $pagination = null): CollectionsR
         );
     }
 
+    /**
+     * Moves a knowledge base to another place in the portal-wide list of knowledge bases.
+     *
+     * `position` is a sort weight: pass a value between the weights of two knowledge bases to land between them,
+     * omit it to land last. The stored weight is recomputed from the neighbours, so read it from the result.
+     * Archived and trashed knowledge bases cannot be moved.
+     *
+     * @link https://apidocs.bitrix24.com/api-reference/note/collection/note-collection-move.html
+     *
+     * @throws BaseException
+     * @throws TransportException
+     */
+    #[ApiEndpointMetadata(
+        'note.collection.move',
+        'https://apidocs.bitrix24.com/api-reference/note/collection/note-collection-move.html',
+        'Moves a knowledge base to another place in the list.',
+        ApiVersion::v3
+    )]
+    public function move(int $id, ?int $position = null): CollectionResult
+    {
+        return new CollectionResult(
+            $this->core->call(
+                'note.collection.move',
+                array_filter(
+                    [
+                        'id'       => $id,
+                        'position' => $position,
+                    ],
+                    static fn (mixed $value): bool => $value !== null
+                ),
+                ApiVersion::v3
+            )
+        );
+    }
+
+    /**
+     * Restores a knowledge base from the recycle bin together with the documents deleted with it.
+     *
+     * A repeated call for a knowledge base that is already out of the recycle bin succeeds.
+     *
+     * @link https://apidocs.bitrix24.com/api-reference/note/collection/note-collection-restore.html
+     *
+     * @throws BaseException
+     * @throws TransportException
+     */
+    #[ApiEndpointMetadata(
+        'note.collection.restore',
+        'https://apidocs.bitrix24.com/api-reference/note/collection/note-collection-restore.html',
+        'Restores a knowledge base from the recycle bin.',
+        ApiVersion::v3
+    )]
+    public function restore(int $id): RestoredCollectionResult
+    {
+        return new RestoredCollectionResult(
+            $this->core->call('note.collection.restore', ['id' => $id], ApiVersion::v3)
+        );
+    }
+
+    /**
+     * Returns a knowledge base from the archive together with its documents.
+     *
+     * A knowledge base that is not archived is reported as not found; a trashed one must be restored first.
+     *
+     * @link https://apidocs.bitrix24.com/api-reference/note/collection/note-collection-unarchive.html
+     *
+     * @throws BaseException
+     * @throws TransportException
+     */
+    #[ApiEndpointMetadata(
+        'note.collection.unarchive',
+        'https://apidocs.bitrix24.com/api-reference/note/collection/note-collection-unarchive.html',
+        'Returns a knowledge base from the archive.',
+        ApiVersion::v3
+    )]
+    public function unarchive(int $id): UnarchivedCollectionResult
+    {
+        return new UnarchivedCollectionResult(
+            $this->core->call('note.collection.unarchive', ['id' => $id], ApiVersion::v3)
+        );
+    }
+
     /**
      * Updates a knowledge base by id or by filter.
      *
-     * @link https://apidocs.bitrix24.com/api-reference/rest-v3/note/collection/note-collection-update.html
+     * @link https://apidocs.bitrix24.com/api-reference/note/collection/note-collection-update.html
      *
      * @param array                        $fields fields to update, e.g. ['name' => 'New name']
      * @param array|FilterBuilderInterface $filter Filter conditions (REST v3 format)
@@ -253,7 +336,7 @@ public function list(?CollectionListPagination $pagination = null): CollectionsR
      */
     #[ApiEndpointMetadata(
         'note.collection.update',
-        'https://apidocs.bitrix24.com/api-reference/rest-v3/note/collection/note-collection-update.html',
+        'https://apidocs.bitrix24.com/api-reference/note/collection/note-collection-update.html',
         'Updates a knowledge base.',
         ApiVersion::v3
     )]