ref #108231 Support knowledge base API

doc/structure.md

@@ -27,6 +27,7 @@ The resource groups list into which client is separated:
 * `features`
 * `files`
 * `integration`
+* [`knowledgeBase`](usage/knowledge-base.md)
 * `loyalty`
 * `notifications`
 * `orders`

doc/usage/knowledge-base.md

@@ -0,0 +1,83 @@
+# Knowledge base
+
+The `knowledgeBase` resource group manages company documents and sections through REST API v5.
+The API key needs `knowledge_base_read` for reads and `knowledge_base_write` for writes.
+Documents are account-wide; there is no `site` parameter.
+
+```php
+use RetailCrm\Api\Factory\SimpleClientFactory;
+use RetailCrm\Api\Model\Entity\KnowledgeBase\KnowledgeBaseDocumentInput;
+use RetailCrm\Api\Model\Request\KnowledgeBase\KnowledgeBaseDocumentByRequest;
+use RetailCrm\Api\Model\Request\KnowledgeBase\KnowledgeBaseDocumentsCreateRequest;
+use RetailCrm\Api\Model\Request\KnowledgeBase\KnowledgeBaseDocumentsEditRequest;
+
+$client = SimpleClientFactory::createClient('https://example.retailcrm.ru', 'apiKey');
+$sections = $client->knowledgeBase->sections()->sections;
+
+$request = new KnowledgeBaseDocumentsCreateRequest();
+$request->document = new KnowledgeBaseDocumentInput();
+$request->document->title = 'Shipping';
+$request->document->content = '# Shipping options';
+$request->document->externalId = 'shipping';
+$request->document->availableForCopilot = true;
+$id = $client->knowledgeBase->documentsCreate($request)->id;
+
+$document = $client->knowledgeBase->documentsGet($id, new KnowledgeBaseDocumentByRequest('id'))->document;
+// Without a by request, the identifier is treated as externalId.
+$document = $client->knowledgeBase->documentsGet('shipping')->document;
+
+$edit = new KnowledgeBaseDocumentsEditRequest();
+$edit->by = 'id';
+$edit->document = new KnowledgeBaseDocumentInput();
+$edit->document->availableForCopilot = false;
+$client->knowledgeBase->documentsEdit($id, $edit);
+```
+
+Only populated input fields are sent on edit. Null properties are omitted, as in other client models.
+Use `sectionId = 0` to remove a document from its section, `parentId = 0` to move a section to the root,
+and `content = ''` to clear text. False boolean values are preserved.
+To send an explicit JSON null (for example, to release an external ID), the edit request also accepts an array:
+
+```php
+$edit = new KnowledgeBaseDocumentsEditRequest();
+$edit->by = 'id';
+$edit->document = ['externalId' => null];
+$client->knowledgeBase->documentsEdit($id, $edit);
+```
+
+Sections are returned without pagination. Documents use `page`, `limit` and a
+`KnowledgeBaseDocumentFilter`: `ids`, `externalIds`, `sectionId`, `directOnly`,
+`availableForCopilot`, `hasFile`, `search`. A section filter includes subsections unless `directOnly` is true.
+With `directOnly = true` and no section, only root documents are selected.
+
+`documentsHistory()` accepts `KnowledgeBaseDocumentsHistoryRequest` and
+`KnowledgeBaseDocumentHistoryFilter` (`sinceId`, `documentId`, `startDate`, `endDate`).
+Store the last history ID to retrieve subsequent changes. Content changes carry hashes, not document text;
+fetch the document again to read the current content. Sections have no history endpoint.
+
+## Files
+
+Use the existing `files->upload()` method to upload the original file, then attach it:
+
+```php
+use RetailCrm\Api\Model\Entity\Files\Attachment;
+use RetailCrm\Api\Model\Entity\Files\AttachmentKnowledgeBaseDocument;
+use RetailCrm\Api\Model\Entity\Files\File;
+use RetailCrm\Api\Model\Request\Files\FilesEditRequest;
+
+$attachment = new Attachment();
+$attachment->knowledgeBaseDocument = new AttachmentKnowledgeBaseDocument();
+$attachment->knowledgeBaseDocument->id = $id;
+$request = new FilesEditRequest();
+$request->file = new File();
+$request->file->filename = 'shipping.pdf';
+$request->file->attachment = [$attachment];
+// $fileId is the ID returned by files->upload().
+$client->files->edit($fileId, $request);
+```
+
+File operations require the corresponding `file_read` / `file_write` scopes.
+A document supports one original file. Its download URL is returned in `document->file->url`.
+
+`sectionsDelete()` deletes the section **together with its subsections and their documents**.
+`documentsDelete()` removes one document and accepts the same `by` request as `documentsGet()`.

src/Client.php

@@ -18,6 +18,7 @@
 use RetailCrm\Api\Interfaces\ResponseTransformerInterface;
 use RetailCrm\Api\ResourceGroup\Api;
 use RetailCrm\Api\ResourceGroup\Costs;
+use RetailCrm\Api\ResourceGroup\KnowledgeBase;
 use RetailCrm\Api\ResourceGroup\CustomerInteraction;
 use RetailCrm\Api\ResourceGroup\Customers;
 use RetailCrm\Api\ResourceGroup\CustomersCorporate;
@@ -65,6 +66,9 @@ class Client
     /** @var \RetailCrm\Api\ResourceGroup\Costs */
     public $costs;
 
+    /** @var \RetailCrm\Api\ResourceGroup\KnowledgeBase */
+    public $knowledgeBase;
+
     /** @var \RetailCrm\Api\ResourceGroup\CustomFields */
     public $customFields;
 
@@ -183,6 +187,14 @@ public function __construct(
             $eventDispatcher,
             $logger
         );
+        $this->knowledgeBase = new KnowledgeBase(
+            $url,
+            $httpClient,
+            $requestTransformer,
+            $responseTransformer,
+            $eventDispatcher,
+            $logger
+        );
         $this->customFields = new CustomFields(
             $url,
             $httpClient,

src/Model/Entity/Files/Attachment.php

@@ -14,6 +14,8 @@
 /**
  * Class Attachment
  *
+ * @SuppressWarnings(PHPMD.LongVariable)
+ *
  * @category Attachment
  * @package  RetailCrm\Api\Model\Entity\Files
  */
@@ -34,4 +36,12 @@ class Attachment
      * @JMS\SerializedName("order")
      */
     public $order;
+
+    /**
+     * @var \RetailCrm\Api\Model\Entity\Files\AttachmentKnowledgeBaseDocument
+     *
+     * @JMS\Type("RetailCrm\Api\Model\Entity\Files\AttachmentKnowledgeBaseDocument")
+     * @JMS\SerializedName("knowledgeBaseDocument")
+     */
+    public $knowledgeBaseDocument;
 }

src/Model/Entity/Files/AttachmentKnowledgeBaseDocument.php

@@ -0,0 +1,29 @@
+<?php
+
+/**
+ * PHP version 7.3
+ *
+ * @category AttachmentKnowledgeBaseDocument
+ * @package  RetailCrm\Api\Model\Entity\Files
+ */
+
+namespace RetailCrm\Api\Model\Entity\Files;
+
+use RetailCrm\Api\Component\Serializer\Annotation as JMS;
+
+/**
+ * Class AttachmentKnowledgeBaseDocument
+ *
+ * @category AttachmentKnowledgeBaseDocument
+ * @package  RetailCrm\Api\Model\Entity\Files
+ */
+class AttachmentKnowledgeBaseDocument
+{
+    /**
+     * @var int
+     *
+     * @JMS\Type("int")
+     * @JMS\SerializedName("id")
+     */
+    public $id;
+}

src/Model/Entity/KnowledgeBase/KnowledgeBaseDocument.php

@@ -0,0 +1,101 @@
+<?php
+
+/**
+ * PHP version 7.3
+ *
+ * @category KnowledgeBaseDocument
+ * @package  RetailCrm\Api\Model\Entity\KnowledgeBase
+ */
+
+namespace RetailCrm\Api\Model\Entity\KnowledgeBase;
+
+use RetailCrm\Api\Component\Serializer\Annotation as JMS;
+
+/**
+ * Class KnowledgeBaseDocument
+ *
+ * @category KnowledgeBaseDocument
+ * @package  RetailCrm\Api\Model\Entity\KnowledgeBase
+ */
+class KnowledgeBaseDocument
+{
+    /**
+     * @var int
+     *
+     * @JMS\Type("int")
+     * @JMS\SerializedName("id")
+     */
+    public $id;
+
+    /**
+     * @var string
+     *
+     * @JMS\Type("string")
+     * @JMS\SerializedName("title")
+     */
+    public $title;
+
+    /**
+     * @var string
+     *
+     * @JMS\Type("string")
+     * @JMS\SerializedName("content")
+     */
+    public $content;
+
+    /**
+     * @var int
+     *
+     * @JMS\Type("int")
+     * @JMS\SerializedName("sectionId")
+     */
+    public $sectionId;
+
+    /**
+     * @var bool
+     *
+     * @JMS\Type("bool")
+     * @JMS\SerializedName("availableForCopilot")
+     */
+    public $availableForCopilot;
+
+    /**
+     * @var string
+     *
+     * @JMS\Type("string")
+     * @JMS\SerializedName("externalId")
+     */
+    public $externalId;
+
+    /**
+     * @var \RetailCrm\Api\Model\Entity\KnowledgeBase\KnowledgeBaseDocumentFile
+     *
+     * @JMS\Type("RetailCrm\Api\Model\Entity\KnowledgeBase\KnowledgeBaseDocumentFile")
+     * @JMS\SerializedName("file")
+     */
+    public $file;
+
+    /**
+     * @var string
+     *
+     * @JMS\Type("string")
+     * @JMS\SerializedName("contentHash")
+     */
+    public $contentHash;
+
+    /**
+     * @var \DateTime
+     *
+     * @JMS\Type("DateTime<'Y-m-d H:i:s'>")
+     * @JMS\SerializedName("createdAt")
+     */
+    public $createdAt;
+
+    /**
+     * @var \DateTime
+     *
+     * @JMS\Type("DateTime<'Y-m-d H:i:s'>")
+     * @JMS\SerializedName("updatedAt")
+     */
+    public $updatedAt;
+}

src/Model/Entity/KnowledgeBase/KnowledgeBaseDocumentFile.php

@@ -0,0 +1,61 @@
+<?php
+
+/**
+ * PHP version 7.3
+ *
+ * @category KnowledgeBaseDocumentFile
+ * @package  RetailCrm\Api\Model\Entity\KnowledgeBase
+ */
+
+namespace RetailCrm\Api\Model\Entity\KnowledgeBase;
+
+use RetailCrm\Api\Component\Serializer\Annotation as JMS;
+
+/**
+ * Class KnowledgeBaseDocumentFile
+ *
+ * @category KnowledgeBaseDocumentFile
+ * @package  RetailCrm\Api\Model\Entity\KnowledgeBase
+ */
+class KnowledgeBaseDocumentFile
+{
+    /**
+     * @var int
+     *
+     * @JMS\Type("int")
+     * @JMS\SerializedName("id")
+     */
+    public $id;
+
+    /**
+     * @var string
+     *
+     * @JMS\Type("string")
+     * @JMS\SerializedName("name")
+     */
+    public $name;
+
+    /**
+     * @var string
+     *
+     * @JMS\Type("string")
+     * @JMS\SerializedName("type")
+     */
+    public $type;
+
+    /**
+     * @var int
+     *
+     * @JMS\Type("int")
+     * @JMS\SerializedName("size")
+     */
+    public $size;
+
+    /**
+     * @var string
+     *
+     * @JMS\Type("string")
+     * @JMS\SerializedName("url")
+     */
+    public $url;
+}