Add API metadata annotations and update notification methods

Added `ApiServiceMetadata` and `ApiEndpointMetadata` annotations to relevant classes and methods. Updated methods to handle system and personal notifications, including new functionalities for deleting and marking notifications as read or unread.

Signed-off-by: mesilov <[email protected]>

CHANGELOG.md

@@ -45,7 +45,7 @@
 * add `Bitrix24\SDK\Infrastructure\Filesystem\Base64Encoder` for work with base64 encoding
 * add `Bitrix24\SDK\Core\Exceptions\FileNotFoundException` if file not found
 * add `Bitrix24\SDK\Core\Exceptions\MethodConfirmWaitingException` if api call waiting for confirm
-* add `Bitrix24\SDK\Core\Exceptions\UserNotFoundOrIsNotActiveException` exception if user not found, or it is not active 
+* add `Bitrix24\SDK\Core\Exceptions\UserNotFoundOrIsNotActiveException` exception if user not found, or it is not active
 * add `Bitrix24\SDK\Core\Result\UserInterfaceDialogCallResult` result of call UI
 * add `Bitrix24\SDK\Core\Result\EmptyResult` empty result
 * add `IncomingRobotRequest` wrapper for data from crm-robot request
@@ -55,15 +55,25 @@
 * add method `Bitrix24\SDK\Application\Requests\Events\AbstractEventRequest::getAuth` - get event auth token
 * add method `Bitrix24\SDK\Application\Requests\Events\EventAuthItem` - event auth token
 * add method `Bitrix24\SDK\Application\Requests\Events\EventInterface` - for event fabrics
-* add method `Bitrix24\SDK\Infrastructure\Filesystem\Base64Encoder::encodeCallRecord(string $filename): string` - for work with call records
+* add method `Bitrix24\SDK\Infrastructure\Filesystem\Base64Encoder::encodeCallRecord(string $filename): string` - for
+  work with call records
 * add class `Bitrix24\SDK\Services\Main\Service\EventManager` - improve DX for work with events lifecycle bind or unbind
 * add method `Bitrix24\SDK\Services\Main\Common\EventHandlerMetadata` - improve DX for work with install events
-* add enum `Bitrix24\SDK\Services\CRM\Common\Result\DiscountType` 
-* improve DX - add [Rector](https://github.com/rectorphp/rector) for improve code quality and speed up releases cycle 
+* add enum `Bitrix24\SDK\Services\CRM\Common\Result\DiscountType`
+* add exception `Bitrix24\SDK\Core\Exceptions\WrongAuthTypeException` – if you use wrong auth type.
+* add class fields filter `Bitrix24\SDK\Core\Fields\FieldsFilter` for fields filtration in result array.
+* improve DX – add [Rector](https://github.com/rectorphp/rector) for improve code quality and speed up releases cycle
+* improve DX – add attributes for generate documentation and calculate methods coverage.
+  * command for generate documentation
+```shell
+     php bin/console b24:util:generate-coverage-documentation 
+```
+* improve DX – add [internal documentation](/docs/EN/documentation.md).
 
 ### Changed
+
 * ❗️ migrate from `ramsey/uuid` to `symfony/uid`
-* ❗️ migrate from  `DateTimeImmutable` to `CarbonImmutable` from [carbon](https://github.com/briannesbitt/carbon) 
+* ❗️ migrate from  `DateTimeImmutable` to `CarbonImmutable` from [carbon](https://github.com/briannesbitt/carbon)
 * ❗️ refactor `Bitrix24\SDK\Application\Contracts`:
 
 * ❗️ update scope `telephony`, scope fully rewritten
@@ -98,34 +108,52 @@
             * `get` - method returns user settings
         * `Voices` - work with voximplant tts voices
             * `get` - method returns all voximplant voices
-      * `Line` - work with voximplant sip lines
-          * `outgoingSipSet` - method sets the selected SIP line as an outgoing line by default.
-          * `get` - returns list of all of the available outgoing lines 
-          * `outgoingGet` - returns the currently selected line as an outgoing line by default. 
-          * `outgoingSet` - sets the selected line as an outgoing line by default. 
-        * `InfoCall` - work with voximplant info call functional
-            * `startWithText` - method performs the call to the specified number with automatic voiceover of specified
-              text
-            * `startWithSound` - method makes a call to the specified number with playback of .mp3 format file by URL.
-        * `Url` - work with links for browsing telephony scope pages
-            * `get` - returns a set of links for browsing telephony scope pages.    
+        * `Line` - work with voximplant sip lines
+            * `outgoingSipSet` - method sets the selected SIP line as an outgoing line by default.
+            * `get` - returns list of all of the available outgoing lines
+            * `outgoingGet` - returns the currently selected line as an outgoing line by default.
+            * `outgoingSet` - sets the selected line as an outgoing line by default.
+            * `InfoCall` - work with voximplant info call functional
+                * `startWithText` - method performs the call to the specified number with automatic voiceover of
+                  specified
+                  text
+                * `startWithSound` - method makes a call to the specified number with playback of .mp3 format file by
+                  URL.
+            * `Url` - work with links for browsing telephony scope pages
+                * `get` - returns a set of links for browsing telephony scope pages.
     * add events with payload and `TelephonyEventsFabric`:
-        *  `OnExternalCallBackStart` - It is called when a visitor fills out a CRM form for callback. Your application shall be selected in the form settings as the line that to be used for a callback.
-        *  `OnExternalCallStart` - The event handler is called whenever a user clicks a phone number in CRM object to initiate an outbound call.
-        *  `OnVoximplantCallEnd` - The event is raised when conversation ends (history entry).
-        *  `OnVoximplantCallInit` - The event is raised when a call is being initialized (regarding the entry or start of an outbound call).
-        *  `OnVoximplantCallStart` - The event is raised when a conversation starts (operator responds to an inbound call; call recipient responds to an outbound call).
+        * `OnExternalCallBackStart` - It is called when a visitor fills out a CRM form for callback. Your application
+          shall be selected in the form settings as the line that to be used for a callback.
+        * `OnExternalCallStart` - The event handler is called whenever a user clicks a phone number in CRM object to
+          initiate an outbound call.
+        * `OnVoximplantCallEnd` - The event is raised when conversation ends (history entry).
+        * `OnVoximplantCallInit` - The event is raised when a call is being initialized (regarding the entry or start of
+          an outbound call).
+        * `OnVoximplantCallStart` - The event is raised when a conversation starts (operator responds to an inbound
+          call; call recipient responds to an outbound call).
     * add `TranscriptMessage` – data structure for transcript message item
     * add `TranscriptMessageSide` – enum for describe side of diarization
     * add `CallType` – call types enum
     * add `CrmEntityType` – crm entity type enum
     * add `PbxType` – pbx type enum
     * add `SipRegistrationStatus` – pbx sip line registration status
-* change signature `Bitrix24\SDK\Core\Credentials\AccessToken::getRefreshToken()?string;` - add nullable option for event tokens
+* ❗️ update scope `im`, add service `Notify`:
+  * `fromSystem` - Sending system notification
+  * `fromPersonal` - Sending personal notification
+  * `delete` – Deleting notification
+  * `markAsRead` - Cancels notification for read messages.
+  * `markMessagesAsRead` – "Read" the list of notifications, excluding CONFIRM notification type.
+  * `markMessagesAsUnread` – "Unread" the list of notifications, excluding CONFIRM notification type.
+  * `confirm` – Interaction with notification buttons
+  * `answer` – Response to notification, supporting quick reply
+* change signature `Bitrix24\SDK\Core\Credentials\AccessToken::getRefreshToken()?string;` - add nullable option for
+  event tokens
 * change signature `Bitrix24\SDK\Core\Commands\Command::getName():?string` renamed to `getId():string`
 * add fields and change return types in `Bitrix24\SDK\Services\CRM\Deal\Result\DealProductRowItemResult`
+* change typehints in `Bitrix24\SDK\Services\CRM\Activity\Service\Activity::add`
 
 ### Deleted
+
 * remove class `Bitrix24\SDK\Application\Requests\Events\OnApplicationInstall\Auth`
 * remove class `Bitrix24\SDK\Application\Requests\Events\OnApplicationUninstall\Auth`
 * remove method `Bitrix24\SDK\Core\Response\Response::__destruct`
@@ -135,9 +163,9 @@
 
 ### Bugfix
 
-* fix [typehint for Bitrix24 User entity with field ID](https://github.com/mesilov/bitrix24-php-sdk/issues/382)    
-* fix [default arguments for Bitrix24 User get method](https://github.com/mesilov/bitrix24-php-sdk/issues/381)    
-* fix [limit argument not worked in batch list and read model](https://github.com/mesilov/bitrix24-php-sdk/issues/389)    
+* fix [typehint for Bitrix24 User entity with field ID](https://github.com/mesilov/bitrix24-php-sdk/issues/382)
+* fix [default arguments for Bitrix24 User get method](https://github.com/mesilov/bitrix24-php-sdk/issues/381)
+* fix [limit argument not worked in batch list and read model](https://github.com/mesilov/bitrix24-php-sdk/issues/389)
 
 ## 2.0-beta.2 — 1.04.2024
 
@@ -223,7 +251,8 @@
 * fix [typehint at ContactItemResult](https://github.com/mesilov/bitrix24-php-sdk/issues/320)
 * fix [return types in DealCategoryItemResult](https://github.com/mesilov/bitrix24-php-sdk/issues/322)
 * fix [add auth node in telephony voximplant events requests](https://github.com/mesilov/bitrix24-php-sdk/issues/331)
-* fix [add helper metods isError for registerCallResult fortelephony](https://github.com/mesilov/bitrix24-php-sdk/issues/335)
+*
+fix [add helper metods isError for registerCallResult fortelephony](https://github.com/mesilov/bitrix24-php-sdk/issues/335)
 * fix [add return type for crm multifields phone, email, im](https://github.com/mesilov/bitrix24-php-sdk/issues/338)
 * fix errors in `ShowFieldsDescriptionCommand` metadata reader CLI command
 * fix errors for `ApplicationProfile` with empty scope
@@ -297,11 +326,13 @@
   , `createFromPlacementRequest`
 *
 
-❗️deleted [unused class](https://github.com/mesilov/bitrix24-php-sdk/issues/303) `Bitrix24\SDK\Core\Response\DTO\ResponseDataCollection`
+❗️deleted [unused class](https://github.com/mesilov/bitrix24-php-sdk/issues/303)
+`Bitrix24\SDK\Core\Response\DTO\ResponseDataCollection`
 
 *
 
-❗️deleted [redundant class](https://github.com/mesilov/bitrix24-php-sdk/issues/303) `Bitrix24\SDK\Core\Response\DTO\Result`
+❗️deleted [redundant class](https://github.com/mesilov/bitrix24-php-sdk/issues/303)
+`Bitrix24\SDK\Core\Response\DTO\Result`
 
 * ❗️deleted [method](https://github.com/mesilov/bitrix24-php-sdk/issues/303) `CoreBuilder::withWebhookUrl`, use
   method `CoreBuilder::withCredentials`

Makefile

@@ -2,13 +2,29 @@ default:
 	@echo "make needs target:"
 	@egrep -e '^\S+' ./Makefile | grep -v default | sed -r 's/://' | sed -r 's/^/ - /'
 
+# load default and personal env-variables
+ENV := $(PWD)/tests/.env
+ENV_LOCAL := $(PWD)/tests/.env.local
+include $(ENV)
+include $(ENV_LOCAL)
+
+debug-show-env:
+	@echo BITRIX24_WEBHOOK $(BITRIX24_WEBHOOK)
+	@echo DOCUMENTATION_DEFAULT_TARGET_BRANCH $(DOCUMENTATION_DEFAULT_TARGET_BRANCH)
+
+# build documentation
+build-documentation:
+	php bin/console b24:util:generate-coverage-documentation --webhook=$(BITRIX24_WEBHOOK) --repository-url=https://github.com/mesilov/bitrix24-php-sdk --repository-branch=$(DOCUMENTATION_DEFAULT_TARGET_BRANCH) --file=docs/EN/Services/bitrix24-php-sdk-methods.md
+
+# linters
 lint-phpstan:
 	vendor/bin/phpstan --memory-limit=1G analyse
 lint-rector:
 	vendor/bin/rector process --dry-run
 lint-rector-fix:
 	vendor/bin/rector process
 
+# unit tests
 test-unit:
 	vendor/bin/phpunit --testsuite unit_tests --display-warnings
 
@@ -17,7 +33,15 @@ test-integration-scope-telephony:
 	vendor/bin/phpunit --testsuite integration_tests_scope_telephony
 test-integration-scope-workflows:
 	vendor/bin/phpunit --testsuite integration_tests_scope_workflows
+test-integration-scope-im:
+	vendor/bin/phpunit --testsuite integration_tests_scope_im
+test-integration-scope-placement:
+	vendor/bin/phpunit --testsuite integration_tests_scope_placement
+test-integration-scope-im-open-lines:
+	vendor/bin/phpunit --testsuite integration_tests_scope_im_open_lines
 test-integration-scope-user:
 	vendor/bin/phpunit --testsuite integration_tests_scope_user
+test-integration-scope-user-consent:
+	vendor/bin/phpunit --testsuite integration_tests_scope_user_consent
 test-integration-core:
 	vendor/bin/phpunit --testsuite integration_tests_core

README.md

@@ -77,6 +77,10 @@ Performance improvements 🚀
     output: b24 response dto
     process: b24 entities, operate with immutable objects  
 ```
+## Documentation
+
+- [Bitrix24 API documentation - English](https://training.bitrix24.com/rest_help/)
+- [Internal documentation](docs/EN/documentation.md) for bitrix24-php-sdk
 
 ## Sponsors
 
@@ -220,8 +224,4 @@ in this project.
 
 ## Need custom Bitrix24 application?
 
-[email protected] for private consultations or dedicated support
-
-## Documentation
-
-[Bitrix24 API documentation - English](https://training.bitrix24.com/rest_help/)
+Email to [email protected] for private consultations or dedicated support.

docs/EN/Development/dev.md

@@ -0,0 +1,17 @@
+# How to build bitrix24-php-sdk
+
+## How to rebuild documentation
+
+Use cli-command
+
+```shell
+make build-documentation
+```
+
+## How to add new scope
+
+1. Add new scope in scope enum `src/Core/Credentials/Scope.php`.
+2. Add new scope folder in `src/Services/` folder and add services.
+3. Add new integration tests in mirror scope folder in `tests/Integration/Services`.
+4. Add new scope support in phpunit `phpunit.xml.dist` testsuite list
+5. Add new scope support in `Makefile`