Feature/603 add call.followup v3

.php-cs-fixer.php

@@ -38,6 +38,8 @@
     ->in(__DIR__ . '/src/Services/IM/')
     ->in(__DIR__ . '/src/Services/IMBot/')
     ->in(__DIR__ . '/src/Services/Catalog/')
+    ->in(__DIR__ . '/src/Services/Telephony/FollowUp/')
+    ->in(__DIR__ . '/src/Services/Telephony/FollowUpField/')
     ->name('*.php')
     ->exclude(['vendor', 'storage', 'docker', 'docs']) // Exclude directories
     ->ignoreDotFiles(true)

CHANGELOG.md

@@ -2,6 +2,15 @@
 
 ## Unreleased
 
+### Added
+
+- Added services `Services\Telephony\FollowUp` and `Services\Telephony\FollowUpField` with support for
+  `call.followup.*` methods, see [call.followup.* methods](https://apidocs.bitrix24.com/api-reference/telephony/follow-up/index.html) ([#603](https://github.com/bitrix24/b24phpsdk/issues/603)):
+    - `call.followup.list` gets a cursor-paginated list of Follow-ups for a period/filter
+    - `call.followup.get` gets a single Follow-up by `callId`
+    - `call.followup.field.list` gets the list of available Follow-up fields
+    - `call.followup.field.get` gets the description of a single Follow-up field by name
+
 ## 3.5.0
 
 ### Added

Makefile

@@ -242,6 +242,10 @@ endif
 test-integration-scope-telephony:
 	docker compose run --rm php-cli $(PHPUNIT) --testsuite integration_tests_scope_telephony
 
+.PHONY: test-integration-telephony-followup
+test-integration-telephony-followup:
+	docker compose run --rm php-cli $(PHPUNIT) --testsuite integration_tests_scope_telephony_followup
+
 .PHONY: test-integration-scope-workflows
 test-integration-scope-workflows:
 	docker compose run --rm php-cli $(PHPUNIT) --testsuite integration_tests_scope_workflows

phpunit.xml.dist

@@ -19,6 +19,12 @@
         <testsuite name="integration_tests_scope_telephony">
             <directory>./tests/Integration/Services/Telephony/</directory>
         </testsuite>
+        <testsuite name="integration_tests_scope_telephony_followup">
+            <directory>./tests/Integration/Services/Telephony/FollowUp/Service/</directory>
+            <directory>./tests/Integration/Services/Telephony/FollowUp/Result/</directory>
+            <directory>./tests/Integration/Services/Telephony/FollowUpField/Service/</directory>
+            <directory>./tests/Integration/Services/Telephony/FollowUpField/Result/</directory>
+        </testsuite>
         <testsuite name="integration_tests_scope_im">
             <directory>./tests/Integration/Services/IM/</directory>
         </testsuite>

src/Services/Telephony/FollowUp/Result/FollowUpItemResult.php

@@ -0,0 +1,52 @@
+<?php
+
+/**
+ * This file is part of the bitrix24-php-sdk package.
+ *
+ * © Dmitriy Ignatenko <algonexys@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\Telephony\FollowUp\Result;
+
+use Bitrix24\SDK\Attributes\OpenApiEntity;
+use Bitrix24\SDK\Core\Result\AbstractAnnotatedItem;
+use Bitrix24\SDK\Services\Telephony\FollowUp\Service\FollowUpSelectBuilder;
+use Carbon\CarbonImmutable;
+
+/**
+ * A single Follow-up (BitrixGPT speech analytics of a video call) returned by
+ * `call.followup.get` / `call.followup.list`.
+ *
+ * @link https://apidocs.bitrix24.com/api-reference/telephony/follow-up/fields.html
+ *
+ * @property-read int                                  $callId
+ * @property-read int                                  $callType
+ * @property-read int                                  $initiatorId
+ * @property-read CarbonImmutable                      $startDate
+ * @property-read CarbonImmutable|null                 $endDate
+ * @property-read int                                  $durationSeconds
+ * @property-read string                                $uuid
+ * @property-read string|null                           $language
+ * @property-read int                                  $version
+ * @property-read array<FollowUpParticipantItemResult>  $participants
+ * @property-read array                                 $outcomes
+ * @property-read CarbonImmutable                       $createdAt
+ * @property-read array<FollowUpTrackItemResult>        $tracks
+ * @property-read array|null                            $transcription
+ * @property-read array|null                            $overview
+ * @property-read array|null                            $summary
+ * @property-read array|null                            $insights
+ * @property-read array|null                             $evaluation
+ */
+#[OpenApiEntity(
+    entityKey:     'bitrix.call.followupdto',
+    selectBuilder: FollowUpSelectBuilder::class,
+)]
+class FollowUpItemResult extends AbstractAnnotatedItem
+{
+}

src/Services/Telephony/FollowUp/Result/FollowUpParticipantItemResult.php

@@ -0,0 +1,31 @@
+<?php
+
+/**
+ * This file is part of the bitrix24-php-sdk package.
+ *
+ * © Dmitriy Ignatenko <algonexys@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\Telephony\FollowUp\Result;
+
+use Bitrix24\SDK\Core\Result\AbstractAnnotatedItem;
+
+/**
+ * A single call participant entry inside `FollowUpItemResult::$participants`.
+ *
+ * @link https://apidocs.bitrix24.com/api-reference/telephony/follow-up/fields.html
+ *
+ * @property-read int         $userId
+ * @property-read string      $name
+ * @property-read int         $talkedSeconds
+ * @property-read string|null $avatar
+ * @property-read string|null $workPosition
+ */
+class FollowUpParticipantItemResult extends AbstractAnnotatedItem
+{
+}

src/Services/Telephony/FollowUp/Result/FollowUpResult.php

@@ -0,0 +1,28 @@
+<?php
+
+/**
+ * This file is part of the bitrix24-php-sdk package.
+ *
+ * © Dmitriy Ignatenko <algonexys@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\Telephony\FollowUp\Result;
+
+use Bitrix24\SDK\Core\Exceptions\BaseException;
+use Bitrix24\SDK\Core\Result\AbstractResult;
+
+class FollowUpResult extends AbstractResult
+{
+    /**
+     * @throws BaseException
+     */
+    public function followUp(): FollowUpItemResult
+    {
+        return new FollowUpItemResult($this->getCoreResponse()->getResponseData()->getResult()['item']);
+    }
+}

src/Services/Telephony/FollowUp/Result/FollowUpTrackItemResult.php

@@ -0,0 +1,39 @@
+<?php
+
+/**
+ * This file is part of the bitrix24-php-sdk package.
+ *
+ * © Dmitriy Ignatenko <algonexys@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\Telephony\FollowUp\Result;
+
+use Bitrix24\SDK\Core\Result\AbstractAnnotatedItem;
+use Carbon\CarbonImmutable;
+
+/**
+ * A single call recording entry inside `FollowUpItemResult::$tracks`.
+ *
+ * @link https://apidocs.bitrix24.com/api-reference/telephony/follow-up/fields.html
+ *
+ * @property-read int             $trackId
+ * @property-read string          $type
+ * @property-read int             $fileId
+ * @property-read int             $diskFileId
+ * @property-read int             $duration
+ * @property-read int             $fileSize
+ * @property-read string          $fileName
+ * @property-read string          $mimeType
+ * @property-read int             $callId
+ * @property-read string          $relUrl
+ * @property-read string          $url
+ * @property-read CarbonImmutable $dateCreate
+ */
+class FollowUpTrackItemResult extends AbstractAnnotatedItem
+{
+}

src/Services/Telephony/FollowUp/Result/FollowUpsResult.php

@@ -0,0 +1,53 @@
+<?php
+
+/**
+ * This file is part of the bitrix24-php-sdk package.
+ *
+ * © Dmitriy Ignatenko <algonexys@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\Telephony\FollowUp\Result;
+
+use Bitrix24\SDK\Core\Exceptions\BaseException;
+use Bitrix24\SDK\Core\Result\AbstractResult;
+use Bitrix24\SDK\Services\Telephony\FollowUp\Service\FollowUpListCursor;
+
+class FollowUpsResult extends AbstractResult
+{
+    /**
+     * @return FollowUpItemResult[]
+     * @throws BaseException
+     */
+    public function getFollowUps(): array
+    {
+        $items = [];
+        foreach ($this->getCoreResponse()->getResponseData()->getResult()['items'] as $item) {
+            $items[] = new FollowUpItemResult($item);
+        }
+
+        return $items;
+    }
+
+    /**
+     * @throws BaseException
+     */
+    public function hasMore(): bool
+    {
+        return (bool)($this->getCoreResponse()->getResponseData()->getResult()['hasMore'] ?? false);
+    }
+
+    /**
+     * @throws BaseException
+     */
+    public function getNextCursor(): ?FollowUpListCursor
+    {
+        $cursor = $this->getCoreResponse()->getResponseData()->getResult()['afterCursor'] ?? null;
+
+        return $cursor === null ? null : FollowUpListCursor::fromArray($cursor);
+    }
+}

src/Services/Telephony/FollowUp/Service/FollowUp.php

@@ -0,0 +1,120 @@
+<?php
+
+/**
+ * This file is part of the bitrix24-php-sdk package.
+ *
+ * © Dmitriy Ignatenko <algonexys@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\Telephony\FollowUp\Service;
+
+use Bitrix24\SDK\Attributes\ApiEndpointMetadata;
+use Bitrix24\SDK\Attributes\ApiServiceMetadata;
+use Bitrix24\SDK\Core\Contracts\ApiVersion;
+use Bitrix24\SDK\Core\Contracts\SelectBuilderInterface;
+use Bitrix24\SDK\Core\Credentials\Scope;
+use Bitrix24\SDK\Core\Exceptions\BaseException;
+use Bitrix24\SDK\Core\Exceptions\TransportException;
+use Bitrix24\SDK\Filters\FilterBuilderInterface;
+use Bitrix24\SDK\Services\AbstractService;
+use Bitrix24\SDK\Services\Telephony\FollowUp\Result\FollowUpResult;
+use Bitrix24\SDK\Services\Telephony\FollowUp\Result\FollowUpsResult;
+
+#[ApiServiceMetadata(new Scope(['call']))]
+class FollowUp extends AbstractService
+{
+    /**
+     * Returns a cursor-paginated list of Follow-ups for a period / filter.
+     *
+     * @link https://apidocs.bitrix24.com/api-reference/telephony/follow-up/call-followup-list.html
+     *
+     * @param array|FilterBuilderInterface        $filter Selection conditions, e.g. a `startDate` range
+     * @param array|FollowUpSelectBuilder         $select Fields and nested paths to return in each item
+     * @param array<string,string>                $order  Sort order, e.g. ['startDate' => 'desc']
+     * @throws BaseException
+     * @throws TransportException
+     */
+    #[ApiEndpointMetadata(
+        'call.followup.list',
+        'https://apidocs.bitrix24.com/api-reference/telephony/follow-up/call-followup-list.html',
+        'Returns a list of Follow-ups for the given period.',
+        ApiVersion::v3
+    )]
+    public function list(
+        array|FilterBuilderInterface $filter,
+        array|FollowUpSelectBuilder $select = [],
+        array $order = ['startDate' => 'desc'],
+        ?FollowUpListPagination $pagination = null,
+        ?FollowUpMentionFormat $mentionFormat = null,
+    ): FollowUpsResult {
+        if ($filter instanceof FilterBuilderInterface) {
+            $filter = $filter->toArray();
+        }
+
+        if ($select instanceof SelectBuilderInterface) {
+            $select = $select->buildSelect();
+        }
+
+        return new FollowUpsResult(
+            $this->core->call(
+                'call.followup.list',
+                array_filter(
+                    [
+                        'filter'        => $filter,
+                        'select'        => $select,
+                        'order'         => $order,
+                        'pagination'    => $pagination?->toArray(),
+                        'mentionFormat' => $mentionFormat?->value,
+                    ],
+                    static fn (mixed $value): bool => $value !== null && $value !== []
+                ),
+                ApiVersion::v3
+            )
+        );
+    }
+
+    /**
+     * Returns a single Follow-up by call identifier.
+     *
+     * @link https://apidocs.bitrix24.com/api-reference/telephony/follow-up/call-followup-get.html
+     *
+     * @param array|FollowUpSelectBuilder $select Fields and nested paths to return; empty select returns all fields
+     * @throws BaseException
+     * @throws TransportException
+     */
+    #[ApiEndpointMetadata(
+        'call.followup.get',
+        'https://apidocs.bitrix24.com/api-reference/telephony/follow-up/call-followup-get.html',
+        'Returns a single Follow-up by call identifier.',
+        ApiVersion::v3
+    )]
+    public function get(
+        int $callId,
+        array|FollowUpSelectBuilder $select = [],
+        ?FollowUpMentionFormat $mentionFormat = null,
+    ): FollowUpResult {
+        if ($select instanceof SelectBuilderInterface) {
+            $select = $select->buildSelect();
+        }
+
+        return new FollowUpResult(
+            $this->core->call(
+                'call.followup.get',
+                array_filter(
+                    [
+                        'callId'        => $callId,
+                        'select'        => $select,
+                        'mentionFormat' => $mentionFormat?->value,
+                    ],
+                    static fn (mixed $value): bool => $value !== null && $value !== []
+                ),
+                ApiVersion::v3
+            )
+        );
+    }
+}