alfa-bank-sdk/src/Requests/NominalAccounts/Beneficiaries/GetBeneficiaryTransactionsRequest.php

<?php

declare(strict_types=1);
/*
// MODULE_CONTRACT: Represents the API call to retrieve transactions for a specific beneficiary.
// RESPONSIBILITY: To encapsulate the HTTP GET request for fetching beneficiary transactions within a specified date range, supporting pagination, and mapping the API response to a typed collection DTO.
// INPUTS: Beneficiary ID, date range (from and to), optional limit and offset for pagination.
// OUTPUTS: A `BeneficiaryTransactionCollectionData` DTO containing a list of transactions.
// LINKS: Data/NominalAccounts/Beneficiaries/BeneficiaryTransactionCollectionData.php, README.md#nominal-accounts
*/

namespace Apoloz\AlfaBank\Requests\NominalAccounts\Beneficiaries;

// <SECTION name="module_imports" intent="Import necessary classes for DTO, HTTP method, and Saloon Request.">
// <BELIEF_STATE "These imports provide the foundational components for defining an API request: `BeneficiaryTransactionCollectionData` for type-safe response handling, `Method` for specifying the HTTP verb, and `Request` and `Response` from Saloon for building the API interaction.">
use Apoloz\AlfaBank\Data\NominalAccounts\Beneficiaries\BeneficiaryTransactionCollectionData;
use Saloon\Enums\Method;
use Saloon\Http\Request;
use Saloon\Http\Response;

// </SECTION>

// <SECTION name="class_definition" intent="Define the request for fetching beneficiary transactions.">
// <BELIEF_STATE "The `GetBeneficiaryTransactionsRequest` class extends Saloon's `Request` to leverage its robust features for API interaction. It sets the HTTP method to GET and defines the structure for constructing the request, including its endpoint, query parameters, and how to transform the API response into a typed DTO.">
class GetBeneficiaryTransactionsRequest extends Request
{
    // <SECTION name="http_method_definition" intent="Define the HTTP method for this request.">
    // <BELIEF_STATE "The request performs a read operation to fetch data, hence the `GET` HTTP method is appropriate and explicitly defined.">
    protected Method $method = Method::GET;
    // </SECTION>

    // <SECTION name="constructor_definition" intent="Initialize the request with beneficiary and date range parameters.">
    // <BELIEF_STATE "The constructor enforces the provision of essential parameters like `beneficiaryId`, `dateFrom`, and `dateTo` to ensure that every request is properly scoped. Optional `limit` and `offset` parameters enable pagination, making the API interaction efficient for large datasets.">
    public function __construct(
        protected string $beneficiaryId,
        protected string $dateFrom,
        protected string $dateTo,
        protected ?int $limit = 100,
        protected ?int $offset = 0
    ) {}
    // </SECTION>

    // <SECTION name="resolve_endpoint" intent="Define the API endpoint for this request.">
    // <BELIEF_STATE "The `resolveEndpoint` method dynamically constructs the API URL using the `beneficiaryId` provided in the constructor. This ensures that the request targets the correct resource for fetching transactions.">
    public function resolveEndpoint(): string
    {
        return "/api/na/jp/v1/beneficiaries/{$this->beneficiaryId}/transactions";
    }
    // </SECTION>

    // <SECTION name="create_dto_from_response" intent="Transform the API response into a `BeneficiaryTransactionCollectionData` DTO.">
    // <BELIEF_STATE "This method is responsible for taking the raw JSON response from the API and converting it into a type-safe `BeneficiaryTransactionCollectionData` object. This ensures that the data consumed by the application is structured, validated, and easy to work with, adhering to the principle of strong typing.">
    public function createDtoFromResponse(Response $response): BeneficiaryTransactionCollectionData
    {
        return BeneficiaryTransactionCollectionData::from($response->json());
    }
    // </SECTION>

    // <SECTION name="default_query_parameters" intent="Define the default query parameters for the request.">
    // <BELIEF_STATE "This method specifies the query parameters (`dateFrom`, `dateTo`, `limit`, `offset`) that will be appended to the request URL. These parameters are crucial for filtering and paginating the transaction data, directly influencing the scope and volume of the API response.">
    protected function defaultQuery(): array
    {
        return [
            'dateFrom' => $this->dateFrom,
            'dateTo' => $this->dateTo,
            'limit' => $this->limit,
            'offset' => $this->offset,
        ];
    }
    // </SECTION>
}
// </SECTION>