Update Bitrix24AccountRepositoryInterface with new methods

This commit expands the Bitrix24AccountRepositoryInterface with new methods for handling Bitrix24 accounts. It includes methods for saving and deleting Bitrix24 accounts, and for fetching accounts by id or specific characteristics. This update provides enhanced functionality to interact with Bitrix24 account data, from basic CRUD operations to more granular lookups based on account status and attributes.

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

phpunit.xml.dist

@@ -7,6 +7,7 @@
         <testsuite name="unit_tests">
             <directory>./tests/Unit</directory>
             <exclude>./tests/Unit/Application/Contracts/Bitrix24Accounts/Entity/Bitrix24AccountInterfaceTest.php</exclude>
+            <exclude>./tests/Unit/Application/Contracts/Bitrix24Accounts/Repository/Bitrix24AccountRepositoryInterfaceTest.php</exclude>
         </testsuite>
         <testsuite name="integration_tests">
             <directory>./tests/Integration</directory>

src/Application/Contracts/Bitrix24Accounts/Docs/Bitrix24Accounts.md

@@ -1,40 +1,65 @@
 # Bitrix24 account entity
 
+| Method                        | Return Type             | Description                                                 | Throws                   |
+|-------------------------------|-------------------------|-------------------------------------------------------------|--------------------------|
+| ` getId()                   ` | `Uuid                 ` | Returns the unique account ID.                              | -                        |
+| ` getBitrix24UserId()       ` | `int                  ` | Returns the Bitrix24 user ID who installed the application. | -                        |
+| ` isBitrix24UserAdmin()     ` | `bool                 ` | Checks if the Bitrix24 user has admin rights.               | -                        |
+| ` getMemberId()             ` | `string               ` | Returns the unique portal ID.                               | -                        |
+| ` getDomainUrl()            ` | `string               ` | Returns the portal domain URL.                              | -                        |
+| ` getStatus()               ` | `Bitrix24AccountStatus` | Returns the account status.                                 | -                        |
+| ` getAuthToken()            ` | `AuthToken            ` | Returns the authentication token.                           | -                        |
+| ` renewAuthToken()          ` | `void                 ` | Renews the authentication token.                            | -                        |
+| ` getApplicationVersion()   ` | `int                  ` | Returns the application version.                            | -                        |
+| ` getApplicationScope()     ` | `Scope                ` | Returns the application scope (permissions).                | -                        |
+| ` changeDomainUrl()         ` | `void                 ` | Changes the domain URL after a portal rename.               | -                        |
+| ` applicationInstalled()    ` | `void                 ` | Sets the account status to "active".                        | InvalidArgumentException |
+| ` applicationUninstalled()  ` | `void                 ` | Sets the account status to "deleted".                       | InvalidArgumentException |
+| ` isApplicationTokenValid() ` | `bool                 ` | Checks if the provided application token is valid.          | -                        |
+| ` getCreatedAt()            ` | `CarbonImmutable      ` | Returns the account creation date and time.                 | -                        |
+| ` getUpdatedAt()            ` | `CarbonImmutable      ` | Returns the last account update date and time.              | -                        |
+| ` updateApplicationVersion()` | `void                 ` | Updates the application version.                            | InvalidArgumentException |
+| ` markAsActive()            ` | `void                 ` | Changes the account status to active.                       | InvalidArgumentException |
+| ` markAsBlocked()           ` | `void                 ` | Changes the account status to blocked.                      | InvalidArgumentException |
+| ` getComment()              ` | `?string              ` | Returns the comment for this account.                       | -                        |
+
+
 ## Bitrix24 account state diagram
 
 ```mermaid
 stateDiagram-v2
-    [*] --> New: New Bitrix24 account\nwhen installation started
-    New --> Active : Installation completed succesfuly
+    [*] --> New: New account when\ninstallation started
+    New --> Active : Installation completed successfully
     New --> Blocked : Installation aborted 
-    Active --> Blocked : Connection lost or\nForcibly deactivated
+    Active --> Blocked : Connection lost or\nforcibly deactivated
     Active --> Deleted : Application\n uninstalled
-    Blocked --> Active : Reconnected or\nReactivated
-    Deleted --> [*]: Bitrix24 account can be removed\n from persistnce storage
+    Blocked --> Active : Reconnected or\nreactivated
+    Blocked --> Deleted : Delete blocked account 
+    Deleted --> [*]: Account can be removed\n from persistence storage
 ```
 
-
 ## Repository methods
 
-- `save(Bitrix24Accounts\Entity\Bitrix24AccountInterface $bitrix24Account): void`
-  - use case Activate
-  - use case Block
-  - use case ChangeDomainUrl
-  - use case InstallStart
-  - use case InstallFinish
-  - use case RenewAuthToken
-  - use case Uninstall
-  - use case UpdateVersion
-- `getById(Uuid $uuid): Bitrix24Accounts\Entity\Bitrix24AccountInterface` 
-  - use case Activate
-  - use case Block
-- `delete(Bitrix24AccountInterface $entity): void`
-  - use case Uninstall
-- `findByMemberId(string $memberId, ?Bitrix24AccountStatus $status = null): array`
-  - use case InstallStart
-  - use case InstallFinish
-  - use case RenewAuthToken
-  - use case Uninstall
-  - use case UpdateVersion (как быть при множественных токенах при обновлении у админа?)
-- `findByDomainUrl(string $domainUrl): array`
-  - use case ChangeDomainUrl
+- `save(Bitrix24AccountInterface $bitrix24Account): void`
+    - use case Activate
+    - use case Block
+    - use case ChangeDomainUrl
+    - use case InstallStart
+    - use case InstallFinish
+    - use case RenewAuthToken
+    - use case Uninstall
+    - use case UpdateVersion
+- `getById(Uuid $uuid): Bitrix24AccountInterface`
+    - use case Activate
+    - use case Block
+- `delete(Uuid $uuid)`
+    - use case Uninstall
+- `findByMemberId(string $memberId, ?Bitrix24AccountStatus $status = null, ?bool $isAdmin = null): array`
+    - use case InstallStart
+    - use case InstallFinish
+    - use case RenewAuthToken
+    - use case Uninstall
+    - use case UpdateVersion (what about multiple accounts???)
+- `findByDomain(string $domainUrl, ?Bitrix24AccountStatus $status = null, ?bool $isAdmin = null): array`
+    - use case ChangeDomainUrl
+- `findOneAdminByMemberId(string $memberId): ?Bitrix24AccountInterface`  

src/Application/Contracts/Bitrix24Accounts/Repository/Bitrix24AccountRepositoryInterface.php

@@ -5,17 +5,50 @@
 namespace Bitrix24\SDK\Application\Contracts\Bitrix24Accounts\Repository;
 
 use Bitrix24\SDK\Application\Contracts\Bitrix24Accounts;
+use Bitrix24\SDK\Application\Contracts\Bitrix24Accounts\Entity\Bitrix24AccountInterface;
+use Bitrix24\SDK\Application\Contracts\Bitrix24Accounts\Entity\Bitrix24AccountStatus;
+use Bitrix24\SDK\Application\Contracts\Bitrix24Accounts\Exceptions\Bitrix24AccountNotFoundException;
+use Bitrix24\SDK\Core\Exceptions\InvalidArgumentException;
 use Symfony\Component\Uid\Uuid;
 
 interface Bitrix24AccountRepositoryInterface
 {
     /**
-     * Get Bitrix24 account by id
+     * Save bitrix24 account to persistence storage
      */
-    public function getById(Uuid $uuid): Bitrix24Accounts\Entity\Bitrix24AccountInterface;
+    public function save(Bitrix24AccountInterface $bitrix24Account): void;
 
     /**
-     * @param bool $isFlush save entity to storage, commit transaction in oltp database
+     * Delete bitrix24 account from
+     * @throws Bitrix24AccountNotFoundException
+     * @throws InvalidArgumentException
      */
-    public function save(Bitrix24Accounts\Entity\Bitrix24AccountInterface $bitrix24Account, bool $isFlush = false): void;
+    public function delete(Uuid $uuid): void;
+
+    /**
+     * Get bitrix24 account by id
+     * @throws Bitrix24AccountNotFoundException
+     */
+    public function getById(Uuid $uuid): Bitrix24AccountInterface;
+
+    /**
+     * Find one admin bitrix24 account by member_id
+     * @param non-empty-string $memberId
+     * @return Bitrix24AccountInterface|null
+     */
+    public function findOneAdminByMemberId(string $memberId): ?Bitrix24AccountInterface;
+
+    /**
+     * Find bitrix24 accounts by member_id and filter by status and isAdmin flag
+     * @param non-empty-string $memberId
+     * @return Bitrix24AccountInterface[]
+     */
+    public function findByMemberId(string $memberId, ?Bitrix24AccountStatus $status = null, ?bool $isAdmin = null): array;
+
+    /**
+     * Find bitrix24 accounts by domain url and filter by status adn isAdmin flag
+     * @param non-empty-string $domainUrl
+     * @return Bitrix24AccountInterface[]
+     */
+    public function findByDomain(string $domainUrl, ?Bitrix24AccountStatus $status = null, ?bool $isAdmin = null): array;
 }