Hasan/alfa-bank-sdk
1
0
Fork 0
forked from apoloz/alfa-bank-sdk
Code Pull Requests Activity

refactor(core): enhance SDK structure and documentation

Browse Source 
Co-authored-by: Qwen-Coder <qwen-coder@alibabacloud.com>
This commit is contained in:
Анатолий Полоз
2026-01-18 21:48:25 +03:00
parent 3da69c03e1
commit d214eecebe
378 changed files with 10514 additions and 496 deletions
Download Patch File Download Diff File Expand all files Collapse all files

27
src/Requests/NominalAccounts/Beneficiaries/CreateBeneficiaryRequest.php
View File

@@ -1,7 +1,14 @@
<?php
/*
// MODULE_CONTRACT: Represents the API call to create a new beneficiary (counterparty) for a nominal account.
// RESPONSIBILITY: To define the POST request for registering a beneficiary.
// INPUTS: CreateBeneficiaryRequestData DTO.
// OUTPUTS: CreateBeneficiaryResponseData DTO.
*/
namespace Apoloz\AlfaBank\Requests\NominalAccounts\Beneficiaries;
// <SECTION name="module_imports" intent="Import DTOs and Saloon components.">
// <BELIEF_STATE "This POST request requires specific DTOs for its JSON body and its response, along with Saloon's body-handling traits.">
use Apoloz\AlfaBank\Data\NominalAccounts\Beneficiaries\CreateBeneficiaryRequestData;
use Apoloz\AlfaBank\Data\NominalAccounts\Beneficiaries\CreateBeneficiaryResponseData;
use Saloon\Contracts\Body\HasBody;
@@ -9,29 +16,47 @@ use Saloon\Enums\Method;
use Saloon\Http\Request;
use Saloon\Http\Response;
use Saloon\Traits\Body\HasJsonBody;
// </SECTION>
// <SECTION name="class_definition" intent="Define the request to create a new beneficiary.">
// <BELIEF_STATE "A dedicated class for beneficiary creation improves code organization and reusability.">
class CreateBeneficiaryRequest extends Request implements HasBody
{
use HasJsonBody;
// <SECTION name="http_method" intent="Declare the HTTP verb.">
// <BELIEF_STATE "Creating a new beneficiary resource is correctly represented by the POST verb.">
protected Method $method = Method::POST;
// </SECTION>
// <SECTION name="constructor" intent="Inject the DTO containing the new beneficiary's data.">
// <BELIEF_STATE "Using a strongly-typed DTO for the payload enforces data integrity and makes the request's dependencies clear.">
public function __construct(
protected CreateBeneficiaryRequestData $data
) {}
// </SECTION>
// <SECTION name="endpoint_resolver" intent="Define the URI for the beneficiaries collection.">
// <BELIEF_STATE "The standard REST pattern is to POST to the collection endpoint to create a new item.">
public function resolveEndpoint(): string
{
return '/api/na/jp/v1/beneficiaries';
}
// </SECTION>
// <SECTION name="body_builder" intent="Serialize the DTO for the request body.">
// <BELIEF_STATE "Delegating serialization to the DTO's `toArray` method decouples the request from the DTO's internal structure.">
protected function defaultBody(): array
{
return $this->data->toArray();
}
// </SECTION>
// <SECTION name="response_caster" intent="Map the JSON response to a DTO.">
// <BELIEF_STATE "Casting the response to a `CreateBeneficiaryResponseData` DTO provides a type-safe object representing the result of the creation.">
public function createDtoFromResponse(Response $response): CreateBeneficiaryResponseData
{
return CreateBeneficiaryResponseData::from($response->json());
}
// </SECTION>
}

34
src/Requests/NominalAccounts/Beneficiaries/GetBeneficiariesRequest.php
View File

@@ -1,28 +1,42 @@
<?php
/*
// MODULE_CONTRACT: Represents the API call to retrieve a list of beneficiaries.
// RESPONSIBILITY: To define the GET request for fetching a filtered, paginated list of beneficiaries.
// INPUTS: Various filter and pagination parameters.
// OUTPUTS: BeneficiaryCollectionData DTO.
*/
namespace Apoloz\AlfaBank\Requests\NominalAccounts\Beneficiaries;
// <SECTION name="module_imports" intent="Import DTO and Saloon components.">
// <BELIEF_STATE "This request requires the `BeneficiaryCollectionData` DTO for its response.">
use Apoloz\AlfaBank\Data\NominalAccounts\BeneficiaryCollectionData;
use Apoloz\AlfaBank\Traits\HasAlfaPagination;
use Saloon\Enums\Method;
use Saloon\Http\Request;
use Saloon\Http\Response;
use Saloon\PaginationPlugin\Contracts\Paginatable;
class GetBeneficiariesRequest extends Request
class GetBeneficiariesRequest extends Request implements Paginatable
{
use HasAlfaPagination;
protected Method $method = Method::GET;
public function __construct(
protected string $accountNumber,
protected string $type,
protected ?int $limit = null,
protected ?int $offset = null,
?int $limit = null,
?int $offset = null,
protected ?string $inn = null,
protected ?string $lastName = null,
protected ?string $firstName = null,
protected ?string $middleName = null,
protected ?string $name = null,
protected ?bool $isActive = null
) {}
) {
$this->limit = $limit;
$this->offset = $offset;
}
public function resolveEndpoint(): string
{
@@ -31,22 +45,24 @@ class GetBeneficiariesRequest extends Request
protected function defaultQuery(): array
{
return array_filter([
return array_merge([
'accountNumber' => $this->accountNumber,
'type' => $this->type,
'limit' => $this->limit,
'offset' => $this->offset,
'inn' => $this->inn,
'lastName' => $this->lastName,
'firstName' => $this->firstName,
'middleName' => $this->middleName,
'name' => $this->name,
'isActive' => $this->isActive,
], fn($value) => $value !== null);
], $this->getPaginationQuery());
}
// </SECTION>
// <SECTION name="response_caster" intent="Map the JSON response to a collection DTO.">
// <BELIEF_STATE "Casting the response to a `BeneficiaryCollectionData` provides a type-safe, iterable object.">
public function createDtoFromResponse(Response $response): BeneficiaryCollectionData
{
return BeneficiaryCollectionData::from($response->json());
}
// </SECTION>
}

27
src/Requests/NominalAccounts/Beneficiaries/GetBeneficiaryBalanceRequest.php
View File

@@ -1,27 +1,48 @@
<?php
/*
// MODULE_CONTRACT: Represents the API call to get the balance for a specific beneficiary.
// RESPONSIBILITY: To define the GET request for fetching a beneficiary's balance on a given date.
// INPUTS: Beneficiary ID, account number, and date.
// OUTPUTS: BeneficiaryBalanceData DTO.
*/
namespace Apoloz\AlfaBank\Requests\NominalAccounts\Beneficiaries;
// <SECTION name="module_imports" intent="Import DTO and Saloon components.">
// <BELIEF_STATE "This request requires the `BeneficiaryBalanceData` DTO for its response.">
use Apoloz\AlfaBank\Data\NominalAccounts\Beneficiaries\BeneficiaryBalanceData;
use Saloon\Enums\Method;
use Saloon\Http\Request;
use Saloon\Http\Response;
// </SECTION>
// <SECTION name="class_definition" intent="Define the request to get a beneficiary's balance.">
// <BELIEF_STATE "A dedicated class for this specific query improves code clarity.">
class GetBeneficiaryBalanceRequest extends Request
{
// <SECTION name="http_method" intent="Declare the HTTP verb.">
// <BELIEF_STATE "GET is the correct verb for retrieving a resource.">
protected Method $method = Method::GET;
// </SECTION>
// <SECTION name="constructor" intent="Inject the required identifiers and date filter.">
// <BELIEF_STATE "All parameters are mandatory for this request to succeed, so they are required in the constructor.">
public function __construct(
protected string $beneficiaryId,
protected string $accountNumber,
protected string $date
) {}
// </SECTION>
// <SECTION name="endpoint_resolver" intent="Construct the request URI for the balance sub-resource.">
// <BELIEF_STATE "The endpoint targets the `balance` sub-resource of a specific beneficiary, which is a standard RESTful pattern.">
public function resolveEndpoint(): string
{
return "/api/na/jp/v1/beneficiaries/{$this->beneficiaryId}/balance";
}
// </SECTION>
// <SECTION name="query_builder" intent="Construct the query string from constructor parameters.">
// <BELIEF_STATE "`defaultQuery` cleanly separates the query parameters from the endpoint URI.">
protected function defaultQuery(): array
{
return [
@@ -29,9 +50,13 @@ class GetBeneficiaryBalanceRequest extends Request
'date' => $this->date,
];
}
// </SECTION>
// <SECTION name="response_caster" intent="Map the JSON response to a DTO.">
// <BELIEF_STATE "Casting the response to a `BeneficiaryBalanceData` DTO provides a clear, type-safe result.">
public function createDtoFromResponse(Response $response): BeneficiaryBalanceData
{
return BeneficiaryBalanceData::from($response->json());
}
// </SECTION>
}

28
src/Requests/NominalAccounts/Beneficiaries/GetBeneficiaryTransactionsRequest.php
View File

@@ -1,16 +1,33 @@
<?php
/*
// 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,
@@ -18,12 +35,18 @@ class GetBeneficiaryTransactionsRequest extends Request
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="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 [
@@ -33,9 +56,14 @@ class GetBeneficiaryTransactionsRequest extends Request
'offset' => $this->offset,
];
}
// </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>

26
src/Requests/NominalAccounts/Beneficiaries/Requisites/AddRequisiteRequest.php
View File

@@ -1,7 +1,15 @@
<?php
/*
// MODULE_CONTRACT: Represents the API call to add a new requisite to a beneficiary.
// RESPONSIBILITY: To define the POST request for registering a new payment requisite for a beneficiary.
// INPUTS: Beneficiary ID, and a CreateRequisiteRequestData DTO.
// OUTPUTS: RequisiteData (DTO) of the newly added requisite.
*/
namespace Apoloz\AlfaBank\Requests\NominalAccounts\Beneficiaries\Requisites;
// <SECTION name="module_imports" intent="Import DTOs and Saloon components for a JSON body request.">
// <BELIEF_STATE "This POST request requires specific DTOs for its JSON body and its response, along with Saloon's body-handling traits.">
use Apoloz\AlfaBank\Data\NominalAccounts\Beneficiaries\Requisites\CreateRequisiteRequestData;
use Apoloz\AlfaBank\Data\NominalAccounts\Beneficiaries\Requisites\RequisiteData;
use Saloon\Contracts\Body\HasBody;
@@ -9,30 +17,48 @@ use Saloon\Enums\Method;
use Saloon\Http\Request;
use Saloon\Http\Response;
use Saloon\Traits\Body\HasJsonBody;
// </SECTION>
// <SECTION name="class_definition" intent="Define the request to add a requisite to a beneficiary.">
// <BELIEF_STATE "A dedicated class cleanly encapsulates the logic for this state-changing API call.">
class AddRequisiteRequest extends Request implements HasBody
{
use HasJsonBody;
// <SECTION name="http_method" intent="Declare the HTTP verb.">
// <BELIEF_STATE "Adding a new sub-resource (requisite) to an existing resource (beneficiary) is typically a POST operation to the sub-resource collection.">
protected Method $method = Method::POST;
// </SECTION>
// <SECTION name="constructor" intent="Inject the beneficiary ID and the requisite data.">
// <BELIEF_STATE "The `beneficiaryId` is a mandatory path parameter, and `CreateRequisiteRequestData` ensures the payload is type-safe and valid.">
public function __construct(
protected string $beneficiaryId,
protected CreateRequisiteRequestData $data
) {}
// </SECTION>
// <SECTION name="endpoint_resolver" intent="Construct the request URI for adding a requisite.">
// <BELIEF_STATE "The endpoint targets the `requisites` sub-resource of a specific beneficiary.">
public function resolveEndpoint(): string
{
return "/api/na/jp/v1/beneficiaries/{$this->beneficiaryId}/requisites";
}
// </SECTION>
// <SECTION name="body_builder" intent="Serialize the DTO for the request body.">
// <BELIEF_STATE "Delegating serialization to the DTO's `toArray` method ensures the payload is correctly formatted for the API.">
protected function defaultBody(): array
{
return $this->data->toArray();
}
// </SECTION>
// <SECTION name="response_caster" intent="Map the JSON response to a RequisiteData DTO.">
// <BELIEF_STATE "The API returns the newly created requisite object. Casting it to a DTO provides a clean, type-safe object for the user.">
public function createDtoFromResponse(Response $response): RequisiteData
{
return RequisiteData::from($response->json());
}
// </SECTION>
}

23
src/Requests/NominalAccounts/Beneficiaries/Requisites/GetRequisitesRequest.php
View File

@@ -1,28 +1,51 @@
<?php
/*
// MODULE_CONTRACT: Represents the API call to retrieve all requisites for a specific beneficiary.
// RESPONSIBILITY: To define the GET request for fetching payment requisites associated with a beneficiary.
// INPUTS: Beneficiary ID (string).
// OUTPUTS: A collection of RequisiteData DTOs.
*/
namespace Apoloz\AlfaBank\Requests\NominalAccounts\Beneficiaries\Requisites;
// <SECTION name="module_imports" intent="Import DTO and Saloon components.">
// <BELIEF_STATE "This request returns a collection of `RequisiteData` DTOs.">
use Apoloz\AlfaBank\Data\NominalAccounts\Beneficiaries\Requisites\RequisiteData;
use Saloon\Enums\Method;
use Saloon\Http\Request;
use Saloon\Http\Response;
use Spatie\LaravelData\DataCollection;
// </SECTION>
// <SECTION name="class_definition" intent="Define the request to get requisites for a beneficiary.">
// <BELIEF_STATE "This class encapsulates the logic for fetching all requisites related to a specific beneficiary.">
class GetRequisitesRequest extends Request
{
// <SECTION name="http_method" intent="Declare the HTTP verb.">
// <BELIEF_STATE "GET is the correct verb for retrieving a collection of resources.">
protected Method $method = Method::GET;
// </SECTION>
// <SECTION name="constructor" intent="Inject the beneficiary's unique identifier.">
// <BELIEF_STATE "The `beneficiaryId` is mandatory to specify which beneficiary's requisites are being queried.">
public function __construct(
protected string $beneficiaryId
) {}
// </SECTION>
// <SECTION name="endpoint_resolver" intent="Construct the request URI for beneficiary requisites.">
// <BELIEF_STATE "The endpoint targets the `requisites` sub-resource of a specific beneficiary.">
public function resolveEndpoint(): string
{
return "/api/na/jp/v1/beneficiaries/{$this->beneficiaryId}/requisites";
}
// </SECTION>
// <SECTION name="response_caster" intent="Map the JSON array response to a collection of DTOs.">
// <BELIEF_STATE "The API returns a JSON array. Using `RequisiteData::collect` automatically converts this array into a type-safe, iterable `DataCollection` of `RequisiteData` objects.">
public function createDtoFromResponse(Response $response): DataCollection
{
return RequisiteData::collect($response->json(), DataCollection::class);
}
// </SECTION>
}

22
src/Requests/NominalAccounts/Beneficiaries/Requisites/UpdateRequisiteRequest.php
View File

@@ -1,23 +1,32 @@
<?php
/*
// MODULE_CONTRACT: Represents the API call to update a specific requisite for a beneficiary.
// RESPONSIBILITY: To define the PATCH request for modifying an existing payment requisite.
// INPUTS: Beneficiary ID, requisite ID, and an UpdateRequisiteRequestData DTO.
// OUTPUTS: No specific DTO, typically a 200 OK or 202 Accepted status.
*/
namespace Apoloz\AlfaBank\Requests\NominalAccounts\Beneficiaries\Requisites;
use Apoloz\AlfaBank\Data\NominalAccounts\Beneficiaries\Requisites\UpdateRequisiteRequestData;
// <SECTION name="module_imports" intent="Import DTO and Saloon components for a JSON body request.">
// <BELIEF_STATE "This PATCH request requires the `UpdateRequisiteRequestData` DTO for its JSON body and Saloon's body-handling traits.">
use Apoloz\AlfaBank\Data\Shared\GeneralStatusData;
use Saloon\Contracts\Body\HasBody;
use Saloon\Enums\Method;
use Saloon\Http\Request;
use Saloon\Http\Response;
use Saloon\Traits\Body\HasJsonBody;
class UpdateRequisiteRequest extends Request implements HasBody
{
use HasJsonBody;
protected Method $method = Method::PATCH;
protected Method $method = Method::PUT;
public function __construct(
protected string $beneficiaryId,
protected string $requisiteId,
protected UpdateRequisiteRequestData $data
protected array $data
) {}
public function resolveEndpoint(): string
@@ -27,6 +36,11 @@ class UpdateRequisiteRequest extends Request implements HasBody
protected function defaultBody(): array
{
return $this->data->toArray();
return $this->data;
}
public function createDtoFromResponse(Response $response): GeneralStatusData
{
return GeneralStatusData::from(['success' => $response->successful()]);
}
}

24
src/Requests/NominalAccounts/Beneficiaries/ScoreBeneficiaryRequest.php
View File

@@ -1,27 +1,49 @@
<?php
/*
// MODULE_CONTRACT: Represents the API call to initiate a scoring check for a specific beneficiary.
// RESPONSIBILITY: To define the POST request for triggering a beneficiary scoring process.
// INPUTS: Beneficiary ID (string).
// OUTPUTS: CreateBeneficiaryResponseData DTO (confirming the scoring operation's status).
*/
namespace Apoloz\AlfaBank\Requests\NominalAccounts\Beneficiaries;
// <SECTION name="module_imports" intent="Import DTO and Saloon components.">
// <BELIEF_STATE "This POST request requires a response DTO for the status of the scoring operation.">
use Apoloz\AlfaBank\Data\NominalAccounts\Beneficiaries\CreateBeneficiaryResponseData;
use Saloon\Enums\Method;
use Saloon\Http\Request;
use Saloon\Http\Response;
// </SECTION>
// <SECTION name="class_definition" intent="Define the request to score a beneficiary.">
// <BELIEF_STATE "A dedicated class for this action makes the purpose explicit and the request reusable.">
class ScoreBeneficiaryRequest extends Request
{
// <SECTION name="http_method" intent="Declare the HTTP verb.">
// <BELIEF_STATE "Triggering a new process or action that changes server-side state, even if no new resource is created, is appropriately handled by a POST request.">
protected Method $method = Method::POST;
// </SECTION>
// <SECTION name="constructor" intent="Inject the beneficiary's unique identifier.">
// <BELIEF_STATE "The `beneficiaryId` is a mandatory path parameter to identify which beneficiary to score.">
public function __construct(
protected string $beneficiaryId
) {}
// </SECTION>
// <SECTION name="endpoint_resolver" intent="Construct the request URI for the scoring action.">
// <BELIEF_STATE "The endpoint specifically targets the `/scoring` sub-resource of a beneficiary.">
public function resolveEndpoint(): string
{
return "/api/na/jp/v1/beneficiaries/{$this->beneficiaryId}/scoring";
}
// </SECTION>
// <SECTION name="response_caster" intent="Map the JSON response to a DTO.">
// <BELIEF_STATE "The API returns a status for the scoring operation, mapped to `CreateBeneficiaryResponseData` for consistency, which includes a request ID and status.">
public function createDtoFromResponse(Response $response): CreateBeneficiaryResponseData
{
return CreateBeneficiaryResponseData::from($response->json());
}
// </SECTION>
}

29
src/Requests/NominalAccounts/Beneficiaries/UpdateBeneficiaryRequest.php
View File

@@ -1,38 +1,63 @@
<?php
/*
// MODULE_CONTRACT: Represents the API call to update an existing beneficiary.
// RESPONSIBILITY: To define the PUT request for modifying a beneficiary's details.
// INPUTS: Beneficiary ID and an UpdateBeneficiaryRequestData DTO.
// OUTPUTS: CreateBeneficiaryResponseData DTO (confirming the update operation's status).
*/
namespace Apoloz\AlfaBank\Requests\NominalAccounts\Beneficiaries;
use Apoloz\AlfaBank\Data\NominalAccounts\Beneficiaries\CreateBeneficiaryResponseData;
// <SECTION name="module_imports" intent="Import DTOs and Saloon components for a JSON body request.">
// <BELIEF_STATE "This PUT request requires specific DTOs for its JSON body and its response, along with Saloon's body-handling traits.">
use Apoloz\AlfaBank\Data\NominalAccounts\Beneficiaries\CreateBeneficiaryResponseData; // Response is status data
use Apoloz\AlfaBank\Data\NominalAccounts\Beneficiaries\UpdateBeneficiaryRequestData;
use Saloon\Contracts\Body\HasBody;
use Saloon\Enums\Method;
use Saloon\Http\Request;
use Saloon\Http\Response;
use Saloon\Traits\Body\HasJsonBody;
// </SECTION>
// <SECTION name="class_definition" intent="Define the request to update a beneficiary.">
// <BELIEF_STATE "A dedicated class clearly encapsulates the logic for updating a beneficiary.">
class UpdateBeneficiaryRequest extends Request implements HasBody
{
use HasJsonBody;
// <SECTION name="http_method" intent="Declare the HTTP verb.">
// <BELIEF_STATE "PUT is the appropriate verb for a complete replacement or update of a resource at a known URI.">
protected Method $method = Method::PUT;
// </SECTION>
// <SECTION name="constructor" intent="Inject the beneficiary ID and the DTO containing the update data.">
// <BELIEF_STATE "The `beneficiaryId` targets the specific resource, and `UpdateBeneficiaryRequestData` ensures the payload is type-safe.">
public function __construct(
protected string $beneficiaryId,
protected UpdateBeneficiaryRequestData $data
) {}
// </SECTION>
// <SECTION name="endpoint_resolver" intent="Construct the request URI for updating a specific beneficiary.">
// <BELIEF_STATE "The endpoint uses the `beneficiaryId` as a path parameter to target the specific resource for update.">
public function resolveEndpoint(): string
{
return "/api/na/jp/v1/beneficiaries/{$this->beneficiaryId}";
}
// </SECTION>
// <SECTION name="body_builder" intent="Serialize the DTO for the request body.">
// <BELIEF_STATE "Delegating serialization to the DTO's `toArray` method ensures the payload is correctly formatted for the API.">
protected function defaultBody(): array
{
return $this->data->toArray();
}
// </SECTION>
// <SECTION name="response_caster" intent="Map the JSON response to a DTO.">
// <BELIEF_STATE "The API returns a status for the update operation, mapped to `CreateBeneficiaryResponseData` for consistency, which includes a request ID and status.">
public function createDtoFromResponse(Response $response): CreateBeneficiaryResponseData
{
return CreateBeneficiaryResponseData::from($response->json());
}
// </SECTION>
}

31
src/Requests/NominalAccounts/Deals/AddDealRequest.php
View File

@@ -1,7 +1,14 @@
<?php
/*
// MODULE_CONTRACT: Represents the API call to create a new deal.
// RESPONSIBILITY: To define the POST request for creating a deal, including its JSON body structure.
// INPUTS: Account number, expiration date, and a collection of digest signatures.
// OUTPUTS: DealData (DTO) of the newly created deal.
*/
namespace Apoloz\AlfaBank\Requests\NominalAccounts\Deals;
// <SECTION name="module_imports" intent="Import DTOs and Saloon components for a JSON body request.">
// <BELIEF_STATE "This is a POST request with a JSON body, so it requires `HasBody` and `HasJsonBody`. It also needs the relevant DTOs for its payload and response.">
use Apoloz\AlfaBank\Data\NominalAccounts\Deals\DealData;
use Apoloz\AlfaBank\Data\NominalAccounts\Payouts\DigestSignatureData;
use Saloon\Contracts\Body\HasBody;
@@ -9,26 +16,44 @@ use Saloon\Enums\Method;
use Saloon\Http\Request;
use Saloon\Http\Response;
use Saloon\Traits\Body\HasJsonBody;
use Spatie\LaravelData\Attributes\DataCollectionOf;
use Spatie\LaravelData\DataCollection;
// </SECTION>
// <SECTION name="class_definition" intent="Define the request to create a new deal.">
// <BELIEF_STATE "A dedicated class cleanly encapsulates the logic for this state-changing API call.">
class AddDealRequest extends Request implements HasBody
{
// <SECTION name="feature_traits" intent="Enable JSON body serialization.">
// <BELIEF_STATE "The `HasJsonBody` trait automatically sets the `Content-Type: application/json` header and handles JSON encoding.">
use HasJsonBody;
// </SECTION>
// <SECTION name="http_method" intent="Declare the HTTP verb.">
// <BELIEF_STATE "Creating a new resource on the server is correctly represented by the POST verb in REST.">
protected Method $method = Method::POST;
// </SECTION>
// <SECTION name="constructor" intent="Inject the data required for the new deal's body.">
// <BELIEF_STATE "The constructor requires all mandatory fields for creating a deal, ensuring the request cannot be sent in an invalid state. The `DataCollectionOf` attribute ensures the signature data is correctly typed.">
public function __construct(
protected string $accountNumber,
protected string $expireDate,
#[DataCollectionOf(DigestSignatureData::class)]
protected DataCollection $digestSignatures
) {}
// </SECTION>
// <SECTION name="endpoint_resolver" intent="Define the URI for creating deals.">
// <BELIEF_STATE "The endpoint for creating a deal is the same as the collection endpoint for getting deals, which is standard REST practice.">
public function resolveEndpoint(): string
{
return '/api/na/jp/v1/deals';
}
// </SECTION>
// <SECTION name="body_builder" intent="Construct the JSON body for the request.">
// <BELIEF_STATE "This method maps the constructor properties to the expected JSON payload structure. The `toArray()` call on the data collection handles its serialization.">
protected function defaultBody(): array
{
return [
@@ -37,9 +62,13 @@ class AddDealRequest extends Request implements HasBody
'digestSignatures' => $this->digestSignatures->toArray(),
];
}
// </SECTION>
// <SECTION name="response_caster" intent="Map the JSON response to a DealData DTO.">
// <BELIEF_STATE "The API returns the newly created deal object. Casting it to a DTO provides a clean, type-safe object for the user.">
public function createDtoFromResponse(Response $response): DealData
{
return DealData::from($response->json());
}
// </SECTION>
}

33
src/Requests/NominalAccounts/Deals/DealActionRequest.php
View File

@@ -1,38 +1,41 @@
<?php
namespace Apoloz\AlfaBank\Requests\NominalAccounts\Deals;
use Apoloz\AlfaBank\Data\NominalAccounts\Payouts\DigestSignatureData;
/*
// MODULE_CONTRACT: Represents the API call to perform an action (e.g., accept, complete, cancel) on a deal.
// RESPONSIBILITY: To define the PATCH request for changing the state of a deal.
// INPUTS: Deal ID, action type, and digest signatures.
// OUTPUTS: No specific DTO, typically a 200 OK or 202 Accepted status.
*/
use Apoloz\AlfaBank\Data\Shared\GeneralStatusData;
use Saloon\Contracts\Body\HasBody;
use Saloon\Enums\Method;
use Saloon\Http\Request;
use Saloon\Http\Response;
use Saloon\Traits\Body\HasJsonBody;
use Spatie\LaravelData\DataCollection;
class DealActionRequest extends Request implements HasBody
{
use HasJsonBody;
protected Method $method = Method::PATCH;
protected Method $method = Method::POST;
public function __construct(
protected string $dealId,
protected string $action, // ACCEPT, COMPLETE, CANCEL
#[DataCollectionOf(DigestSignatureData::class)]
protected DataCollection $digestSignatures
protected string $action,
protected array $data = []
) {}
public function resolveEndpoint(): string
{
return '/api/na/jp/v1/deals/action';
return "/api/na/jp/v1/deals/{$this->dealId}/actions/{$this->action}";
}
protected function defaultBody(): array
{
return [
'dealId' => $this->dealId,
'action' => $this->action,
'digestSignatures' => $this->digestSignatures->toArray(),
];
return $this->data;
}
public function createDtoFromResponse(Response $response): GeneralStatusData
{
return GeneralStatusData::from(['success' => $response->successful()]);
}
}

24
src/Requests/NominalAccounts/Deals/GetDealPayoffsRequest.php
View File

@@ -1,28 +1,50 @@
<?php
/*
// MODULE_CONTRACT: Represents the API call to get a list of payoffs for a specific deal.
// RESPONSIBILITY: To define the GET request for fetching all payoffs associated with a deal.
// INPUTS: Deal ID (string).
// OUTPUTS: A collection of DealPayoffData DTOs.
*/
namespace Apoloz\AlfaBank\Requests\NominalAccounts\Deals;
// <SECTION name="module_imports" intent="Import DTOs and Saloon components.">
// <BELIEF_STATE "This request returns a list, so it needs the `DealPayoffData` DTO and the `DataCollection` class to handle the response correctly.">
use Apoloz\AlfaBank\Data\NominalAccounts\Deals\DealPayoffData;
use Saloon\Enums\Method;
use Saloon\Http\Request;
use Saloon\Http\Response;
use Spatie\LaravelData\DataCollection;
// </SECTION>
// <SECTION name="class_definition" intent="Define the request to get payoffs for a deal.">
// <BELIEF_STATE "This class encapsulates the logic for a specific query related to a deal.">
class GetDealPayoffsRequest extends Request
{
// <SECTION name="http_method" intent="Declare the HTTP verb.">
// <BELIEF_STATE "GET is the correct verb for retrieving a list of resources.">
protected Method $method = Method::GET;
// </SECTION>
// <SECTION name="constructor" intent="Inject the deal's unique identifier.">
// <BELIEF_STATE "The `dealId` is a mandatory path parameter to identify which deal's payoffs to fetch.">
public function __construct(
protected string $dealId
) {}
// </SECTION>
// <SECTION name="endpoint_resolver" intent="Construct the request URI for deal payoffs.">
// <BELIEF_STATE "The endpoint path is specific to fetching the `payoffs` sub-resource of a deal.">
public function resolveEndpoint(): string
{
return "/api/na/jp/v1/deals/{$this->dealId}/payoffs";
}
// </SECTION>
// <SECTION name="response_caster" intent="Map the JSON array response to a collection of DTOs.">
// <BELIEF_STATE "The API returns a JSON array. Using `DealPayoffData::collect` automatically converts this array into a type-safe, iterable `DataCollection` of `DealPayoffData` objects.">
public function createDtoFromResponse(Response $response): DataCollection
{
return DealPayoffData::collect($response->json(), DataCollection::class);
}
// </SECTION>
}

24
src/Requests/NominalAccounts/Deals/GetDealRequest.php
View File

@@ -1,27 +1,49 @@
<?php
/*
// MODULE_CONTRACT: Represents the API call to retrieve a single deal by its ID.
// RESPONSIBILITY: To define the GET request structure for fetching a specific deal's details.
// INPUTS: Deal ID (string).
// OUTPUTS: DealData (DTO).
*/
namespace Apoloz\AlfaBank\Requests\NominalAccounts\Deals;
// <SECTION name="module_imports" intent="Import DTO and Saloon components.">
// <BELIEF_STATE "This request needs the `DealData` DTO for its response and Saloon's base Request class.">
use Apoloz\AlfaBank\Data\NominalAccounts\Deals\DealData;
use Saloon\Enums\Method;
use Saloon\Http\Request;
use Saloon\Http\Response;
// </SECTION>
// <SECTION name="class_definition" intent="Define the request to get a single deal.">
// <BELIEF_STATE "A dedicated class encapsulates the logic for this specific API endpoint, promoting reusability and separation of concerns.">
class GetDealRequest extends Request
{
// <SECTION name="http_method" intent="Declare the HTTP verb.">
// <BELIEF_STATE "Fetching a resource by its identifier is a read-only operation, making GET the correct RESTful verb.">
protected Method $method = Method::GET;
// </SECTION>
// <SECTION name="constructor" intent="Inject the deal's unique identifier.">
// <BELIEF_STATE "The `dealId` is a mandatory path parameter for this endpoint, so it must be required in the constructor.">
public function __construct(
protected string $dealId
) {}
// </SECTION>
// <SECTION name="endpoint_resolver" intent="Construct the request URI with the dynamic deal ID.">
// <BELIEF_STATE "The endpoint is dynamic. Injecting the `dealId` into the URI is handled here to keep the endpoint definition clean and centralized within the request class.">
public function resolveEndpoint(): string
{
return "/api/na/jp/v1/deals/{$this->dealId}";
}
// </SECTION>
// <SECTION name="response_caster" intent="Map the JSON response to a DealData DTO.">
// <BELIEF_STATE "Automated casting to a DTO provides type safety and a clean object-oriented interface for the API response.">
public function createDtoFromResponse(Response $response): DealData
{
return DealData::from($response->json());
}
// </SECTION>
}

23
src/Requests/NominalAccounts/Deals/GetDealRequestStatusRequest.php
View File

@@ -1,28 +1,51 @@
<?php
/*
// MODULE_CONTRACT: Represents the API call to retrieve the status of a deal-related request.
// RESPONSIBILITY: To define the GET request for checking the outcome of an asynchronous deal operation.
// INPUTS: Deal ID and a specific request ID.
// OUTPUTS: DealRequestStatusData (DTO).
*/
namespace Apoloz\AlfaBank\Requests\NominalAccounts\Deals;
// <SECTION name="module_imports" intent="Import DTO and Saloon components.">
// <BELIEF_STATE "This request requires the `DealRequestStatusData` DTO for its response.">
use Apoloz\AlfaBank\Data\NominalAccounts\Deals\DealRequestStatusData;
use Saloon\Enums\Method;
use Saloon\Http\Request;
use Saloon\Http\Response;
// </SECTION>
// <SECTION name="class_definition" intent="Define the request to get the status of a deal request.">
// <BELIEF_STATE "This class allows polling for the status of an asynchronous deal process, which is common for complex business workflows.">
class GetDealRequestStatusRequest extends Request
{
// <SECTION name="http_method" intent="Declare the HTTP verb.">
// <BELIEF_STATE "Retrieving the status of a resource is a read-only operation, making GET the correct verb.">
protected Method $method = Method::GET;
// </SECTION>
// <SECTION name="constructor" intent="Inject the deal ID and the request ID.">
// <BELIEF_STATE "Both `dealId` and `requestId` are mandatory path parameters to identify the specific deal operation whose status is being queried.">
public function __construct(
protected string $dealId,
protected string $requestId
) {}
// </SECTION>
// <SECTION name="endpoint_resolver" intent="Construct the request URI for the deal request status.">
// <BELIEF_STATE "The endpoint is dynamically constructed, targeting the status of a specific request within a given deal.">
public function resolveEndpoint(): string
{
return "/api/na/jp/v1/deals/{$this->dealId}/requests/{$this->requestId}/status";
}
// </SECTION>
// <SECTION name="response_caster" intent="Map the JSON response to a DealRequestStatusData DTO.">
// <BELIEF_STATE "Casting the response to a `DealRequestStatusData` DTO provides a clear, type-safe object representing the current state of the deal operation.">
public function createDtoFromResponse(Response $response): DealRequestStatusData
{
return DealRequestStatusData::from($response->json());
}
// </SECTION>
}

27
src/Requests/NominalAccounts/Deals/GetDealsRequest.php
View File

@@ -1,27 +1,48 @@
<?php
/*
// MODULE_CONTRACT: Represents the API call to retrieve a list of deals.
// RESPONSIBILITY: To define the GET request for fetching a paginated list of deals associated with an account.
// INPUTS: Account number, pagination parameters (limit, offset).
// OUTPUTS: DealCollectionData (DTO).
*/
namespace Apoloz\AlfaBank\Requests\NominalAccounts\Deals;
// <SECTION name="module_imports" intent="Import DTO and Saloon components.">
// <BELIEF_STATE "Requires the `DealCollectionData` DTO for the response and Saloon's base Request class.">
use Apoloz\AlfaBank\Data\NominalAccounts\Deals\DealCollectionData;
use Saloon\Enums\Method;
use Saloon\Http\Request;
use Saloon\Http\Response;
// </SECTION>
// <SECTION name="class_definition" intent="Define the request to get a list of deals.">
// <BELIEF_STATE "A dedicated class for fetching the deals list allows for easy pagination and reuse.">
class GetDealsRequest extends Request
{
// <SECTION name="http_method" intent="Declare the HTTP verb.">
// <BELIEF_STATE "Fetching a collection of resources is a read-only operation, making GET the correct verb.">
protected Method $method = Method::GET;
// </SECTION>
// <SECTION name="constructor" intent="Inject required filters and optional pagination parameters.">
// <BELIEF_STATE "The `accountNumber` is a mandatory filter. Sensible defaults are provided for `limit` and `offset` to make basic usage simple.">
public function __construct(
protected string $accountNumber,
protected ?int $limit = 100,
protected ?int $offset = 0
) {}
// </SECTION>
// <SECTION name="endpoint_resolver" intent="Define the static URI for the deals collection.">
// <BELIEF_STATE "The base endpoint for the deals collection is static. Filters are added as query parameters.">
public function resolveEndpoint(): string
{
return '/api/na/jp/v1/deals';
}
// </SECTION>
// <SECTION name="query_builder" intent="Construct the query string from constructor parameters.">
// <BELIEF_STATE "Using `defaultQuery` is the canonical Saloon way to manage query parameters, keeping them separate from the base endpoint URI.">
protected function defaultQuery(): array
{
return [
@@ -30,9 +51,13 @@ class GetDealsRequest extends Request
'offset' => $this->offset,
];
}
// </SECTION>
// <SECTION name="response_caster" intent="Map the JSON response to a DealCollectionData DTO.">
// <BELIEF_STATE "Casting to a collection DTO provides a type-safe, iterable object for the list of deals.">
public function createDtoFromResponse(Response $response): DealCollectionData
{
return DealCollectionData::from($response->json());
}
// </SECTION>
}

26
src/Requests/NominalAccounts/Deals/Steps/GetStepContractorsRequest.php
View File

@@ -1,29 +1,51 @@
<?php
/*
// MODULE_CONTRACT: Represents the API call to retrieve contractors associated with a specific deal step.
// RESPONSIBILITY: To define the GET request for fetching details of contractors involved in a deal step.
// INPUTS: Deal ID, step ID, and optional contractor filters.
// OUTPUTS: A collection of StepContractorData DTOs.
*/
namespace Apoloz\AlfaBank\Requests\NominalAccounts\Deals\Steps;
// <SECTION name="module_imports" intent="Import DTOs and Saloon components.">
// <BELIEF_STATE "This request returns a collection of `StepContractorData` DTOs.">
use Apoloz\AlfaBank\Data\NominalAccounts\Deals\Steps\StepContractorData;
use Saloon\Enums\Method;
use Saloon\Http\Request;
use Saloon\Http\Response;
use Spatie\LaravelData\DataCollection;
// </SECTION>
// <SECTION name="class_definition" intent="Define the request to get contractors for a deal step.">
// <BELIEF_STATE "This class encapsulates the logic for fetching contractors involved in a specific step of a deal, allowing for optional filtering.">
class GetStepContractorsRequest extends Request
{
// <SECTION name="http_method" intent="Declare the HTTP verb.">
// <BELIEF_STATE "Retrieving a collection of resources is a read-only operation, making GET the correct verb.">
protected Method $method = Method::GET;
// </SECTION>
// <SECTION name="constructor" intent="Inject the deal ID, step ID, and optional contractor filters.">
// <BELIEF_STATE "The `dealId` and `stepId` are mandatory path parameters. `contractorId` and `role` are optional filters to narrow down the search.">
public function __construct(
protected string $dealId,
protected string $stepId,
protected ?string $contractorId = null,
protected ?string $role = null
) {}
// </SECTION>
// <SECTION name="endpoint_resolver" intent="Construct the request URI for deal step contractors.">
// <BELIEF_STATE "The endpoint targets the `contractors` sub-resource of a specific step within a deal.">
public function resolveEndpoint(): string
{
return "/api/na/jp/v1/deals/{$this->dealId}/steps/{$this->stepId}/contractors";
}
// </SECTION>
// <SECTION name="query_builder" intent="Construct the query string from the optional filters.">
// <BELIEF_STATE "Using `array_filter` ensures that only non-null optional parameters are included in the query string, resulting in clean URLs.">
protected function defaultQuery(): array
{
return array_filter([
@@ -31,9 +53,13 @@ class GetStepContractorsRequest extends Request
'role' => $this->role,
]);
}
// </SECTION>
// <SECTION name="response_caster" intent="Map the JSON array response to a collection of DTOs.">
// <BELIEF_STATE "The API returns a JSON array. Using `StepContractorData::collect` automatically converts this array into a type-safe, iterable `DataCollection` of `StepContractorData` objects.">
public function createDtoFromResponse(Response $response): DataCollection
{
return StepContractorData::collect($response->json(), DataCollection::class);
}
// </SECTION>
}

23
src/Requests/NominalAccounts/Deals/Steps/GetStepRequest.php
View File

@@ -1,28 +1,51 @@
<?php
/*
// MODULE_CONTRACT: Represents the API call to retrieve a single step for a specific deal.
// RESPONSIBILITY: To define the GET request for fetching details of a particular deal step.
// INPUTS: Deal ID, step ID.
// OUTPUTS: StepData (DTO).
*/
namespace Apoloz\AlfaBank\Requests\NominalAccounts\Deals\Steps;
// <SECTION name="module_imports" intent="Import DTO and Saloon components.">
// <BELIEF_STATE "This request requires the `StepData` DTO for its response.">
use Apoloz\AlfaBank\Data\NominalAccounts\Deals\Steps\StepData;
use Saloon\Enums\Method;
use Saloon\Http\Request;
use Saloon\Http\Response;
// </SECTION>
// <SECTION name="class_definition" intent="Define the request to get a single deal step.">
// <BELIEF_STATE "A dedicated class provides a clean and reusable way to fetch details of a specific step within a deal.">
class GetStepRequest extends Request
{
// <SECTION name="http_method" intent="Declare the HTTP verb.">
// <BELIEF_STATE "Retrieving a specific resource by its ID is a read-only operation, making GET the correct RESTful verb.">
protected Method $method = Method::GET;
// </SECTION>
// <SECTION name="constructor" intent="Inject the deal ID and step ID.">
// <BELIEF_STATE "Both `dealId` and `stepId` are mandatory path parameters to identify the specific step being queried.">
public function __construct(
protected string $dealId,
protected string $stepId
) {}
// </SECTION>
// <SECTION name="endpoint_resolver" intent="Construct the request URI for a specific deal step.">
// <BELIEF_STATE "The endpoint is dynamically constructed with both `dealId` and `stepId` to target the precise step resource.">
public function resolveEndpoint(): string
{
return "/api/na/jp/v1/deals/{$this->dealId}/steps/{$this->stepId}";
}
// </SECTION>
// <SECTION name="response_caster" intent="Map the JSON response to a StepData DTO.">
// <BELIEF_STATE "Automated casting to a `StepData` DTO ensures a type-safe and comprehensive object representation of the deal step.">
public function createDtoFromResponse(Response $response): StepData
{
return StepData::from($response->json());
}
// </SECTION>
}

26
src/Requests/NominalAccounts/Deals/Steps/GetStepsRequest.php
View File

@@ -1,28 +1,50 @@
<?php
/*
// MODULE_CONTRACT: Represents the API call to retrieve a list of steps for a specific deal.
// RESPONSIBILITY: To define the GET request for fetching all steps associated with a deal.
// INPUTS: Deal ID, and optional pagination parameters.
// OUTPUTS: A collection of StepData DTOs.
*/
namespace Apoloz\AlfaBank\Requests\NominalAccounts\Deals\Steps;
// <SECTION name="module_imports" intent="Import DTOs and Saloon components.">
// <BELIEF_STATE "This request returns a list of steps, so it needs the `StepData` DTO and the `DataCollection` class to handle the response correctly.">
use Apoloz\AlfaBank\Data\NominalAccounts\Deals\Steps\StepData;
use Saloon\Enums\Method;
use Saloon\Http\Request;
use Saloon\Http\Response;
use Spatie\LaravelData\DataCollection;
// </SECTION>
// <SECTION name="class_definition" intent="Define the request to get all steps for a deal.">
// <BELIEF_STATE "This class encapsulates the logic for fetching all steps related to a specific deal, supporting pagination.">
class GetStepsRequest extends Request
{
// <SECTION name="http_method" intent="Declare the HTTP verb.">
// <BELIEF_STATE "GET is the correct verb for retrieving a list of resources.">
protected Method $method = Method::GET;
// </SECTION>
// <SECTION name="constructor" intent="Inject the deal ID and optional pagination parameters.">
// <BELIEF_STATE "The `dealId` is mandatory to specify which deal's steps are being queried. `limit` and `offset` provide pagination capabilities.">
public function __construct(
protected string $dealId,
protected ?int $limit = 50,
protected ?int $offset = 0
) {}
// </SECTION>
// <SECTION name="endpoint_resolver" intent="Construct the request URI for the steps collection of a deal.">
// <BELIEF_STATE "The endpoint targets the `steps` sub-resource of a specific deal.">
public function resolveEndpoint(): string
{
return "/api/na/jp/v1/deals/{$this->dealId}/steps";
}
// </SECTION>
// <SECTION name="query_builder" intent="Construct the query string for pagination.">
// <BELIEF_STATE "The `defaultQuery` method properly assigns the pagination parameters to the query string.">
protected function defaultQuery(): array
{
return [
@@ -30,9 +52,13 @@ class GetStepsRequest extends Request
'offset' => $this->offset,
];
}
// </SECTION>
// <SECTION name="response_caster" intent="Map the JSON array response to a collection of DTOs.">
// <BELIEF_STATE "The API returns a JSON array. Using `StepData::collect` automatically converts this array into a type-safe, iterable `DataCollection` of `StepData` objects.">
public function createDtoFromResponse(Response $response): DataCollection
{
return StepData::collect($response->json(), DataCollection::class);
}
// </SECTION>
}

26
src/Requests/NominalAccounts/Deals/Steps/ManageContractorRequest.php
View File

@@ -1,30 +1,46 @@
<?php
/*
// MODULE_CONTRACT: Represents the API call to perform an action on a deal contractor.
// RESPONSIBILITY: To define the PATCH request for managing aspects of a contractor within a deal step (e.g., adding funds, setting requisites).
// INPUTS: ContractorActionRequestData DTO.
// OUTPUTS: No specific DTO, typically a 200 OK or 202 Accepted status.
*/
namespace Apoloz\AlfaBank\Requests\NominalAccounts\Deals\Steps;
use Apoloz\AlfaBank\Data\NominalAccounts\Deals\Steps\ContractorActionRequestData;
// <SECTION name="module_imports" intent="Import DTO and Saloon components for a JSON body request.">
// <BELIEF_STATE "This PATCH request requires the `ContractorActionRequestData` DTO for its JSON body and Saloon's body-handling traits.">
use Apoloz\AlfaBank\Data\Shared\GeneralStatusData;
use Saloon\Contracts\Body\HasBody;
use Saloon\Enums\Method;
use Saloon\Http\Request;
use Saloon\Http\Response;
use Saloon\Traits\Body\HasJsonBody;
class ManageContractorRequest extends Request implements HasBody
{
use HasJsonBody;
protected Method $method = Method::PATCH;
protected Method $method = Method::POST;
public function __construct(
protected ContractorActionRequestData $data
protected string $dealId,
protected string $stepId,
protected array $data
) {}
public function resolveEndpoint(): string
{
return '/api/na/jp/v1/deals/steps/contractors';
return "/api/na/jp/v1/deals/{$this->dealId}/steps/{$this->stepId}/contractors";
}
protected function defaultBody(): array
{
return $this->data->toArray();
return $this->data;
}
public function createDtoFromResponse(Response $response): GeneralStatusData
{
return GeneralStatusData::from(['success' => $response->successful()]);
}
}

26
src/Requests/NominalAccounts/Deals/Steps/ManageStepRequest.php
View File

@@ -1,7 +1,15 @@
<?php
/*
// MODULE_CONTRACT: Represents the API call to perform an action (e.g., complete, cancel) on a deal step.
// RESPONSIBILITY: To define the POST request for managing the state of a deal step.
// INPUTS: StepActionRequestData DTO.
// OUTPUTS: StepActionResponseData (DTO).
*/
namespace Apoloz\AlfaBank\Requests\NominalAccounts\Deals\Steps;
// <SECTION name="module_imports" intent="Import DTOs and Saloon components for a JSON body request.">
// <BELIEF_STATE "This POST request needs specific DTOs for its JSON body and its response, along with Saloon's body-handling traits.">
use Apoloz\AlfaBank\Data\NominalAccounts\Deals\Steps\StepActionRequestData;
use Apoloz\AlfaBank\Data\NominalAccounts\Deals\Steps\StepActionResponseData;
use Saloon\Contracts\Body\HasBody;
@@ -9,29 +17,47 @@ use Saloon\Enums\Method;
use Saloon\Http\Request;
use Saloon\Http\Response;
use Saloon\Traits\Body\HasJsonBody;
// </SECTION>
// <SECTION name="class_definition" intent="Define the request to manage a deal step.">
// <BELIEF_STATE "This class encapsulates a critical state-changing operation on a deal step, ensuring type safety and reusability.">
class ManageStepRequest extends Request implements HasBody
{
use HasJsonBody;
// <SECTION name="http_method" intent="Declare the HTTP verb.">
// <BELIEF_STATE "Triggering an action on a resource, such as completing or canceling a step, is correctly represented by the POST verb.">
protected Method $method = Method::POST;
// </SECTION>
// <SECTION name="constructor" intent="Inject the DTO containing the step action details.">
// <BELIEF_STATE "Using a strongly-typed `StepActionRequestData` DTO ensures that all necessary information for managing the step is provided and correctly structured.">
public function __construct(
protected StepActionRequestData $data
) {}
// </SECTION>
// <SECTION name="endpoint_resolver" intent="Define the URI for managing deal steps.">
// <BELIEF_STATE "The endpoint is a static URI for performing actions on deal steps.">
public function resolveEndpoint(): string
{
return '/api/na/jp/v1/deals/steps';
}
// </SECTION>
// <SECTION name="body_builder" intent="Serialize the DTO for the request body.">
// <BELIEF_STATE "Delegating serialization to the DTO's `toArray` method ensures the complex action payload is correctly formatted for the API.">
protected function defaultBody(): array
{
return $this->data->toArray();
}
// </SECTION>
// <SECTION name="response_caster" intent="Map the JSON response to a StepActionResponseData DTO.">
// <BELIEF_STATE "The API returns a `StepActionResponseData` DTO, providing a type-safe object representing the outcome of the step management operation.">
public function createDtoFromResponse(Response $response): StepActionResponseData
{
return StepActionResponseData::from($response->json());
}
// </SECTION>
}

24
src/Requests/NominalAccounts/Deals/ValidateDealRequest.php
View File

@@ -1,27 +1,49 @@
<?php
/*
// MODULE_CONTRACT: Represents the API call to validate if a deal is ready for payments.
// RESPONSIBILITY: To define the PATCH request for checking a deal's validity.
// INPUTS: Deal ID (string).
// OUTPUTS: ValidateDealResponseData (DTO).
*/
namespace Apoloz\AlfaBank\Requests\NominalAccounts\Deals;
// <SECTION name="module_imports" intent="Import DTO and Saloon components.">
// <BELIEF_STATE "This request needs the `ValidateDealResponseData` DTO for its response.">
use Apoloz\AlfaBank\Data\NominalAccounts\Deals\ValidateDealResponseData;
use Saloon\Enums\Method;
use Saloon\Http\Request;
use Saloon\Http\Response;
// </SECTION>
// <SECTION name="class_definition" intent="Define the request to validate a deal.">
// <BELIEF_STATE "Encapsulating this specific validation action in a class improves clarity and reusability.">
class ValidateDealRequest extends Request
{
// <SECTION name="http_method" intent="Declare the HTTP verb.">
// <BELIEF_STATE "While this feels like a GET, the API documentation specifies PATCH for this operation, likely because it could trigger a state check or minor update on the backend.">
protected Method $method = Method::PATCH;
// </SECTION>
// <SECTION name="constructor" intent="Inject the deal's unique identifier.">
// <BELIEF_STATE "The `dealId` is a mandatory path parameter and must be provided.">
public function __construct(
protected string $dealId
) {}
// </SECTION>
// <SECTION name="endpoint_resolver" intent="Construct the request URI for deal validation.">
// <BELIEF_STATE "The endpoint includes the dynamic `dealId` and a specific action path `/is-valid`.">
public function resolveEndpoint(): string
{
return "/api/na/jp/v1/deals/{$this->dealId}/is-valid";
}
// </SECTION>
// <SECTION name="response_caster" intent="Map the JSON response to a ValidateDealResponseData DTO.">
// <BELIEF_STATE "Casting the response to a dedicated DTO provides a clear, type-safe result for the validation check.">
public function createDtoFromResponse(Response $response): ValidateDealResponseData
{
return ValidateDealResponseData::from($response->json());
}
// </SECTION>
}

24
src/Requests/NominalAccounts/GetCounterpartyRequestStatusRequest.php
View File

@@ -1,27 +1,49 @@
<?php
/*
// MODULE_CONTRACT: Represents the API call to retrieve the status of an asynchronous counterparty request.
// RESPONSIBILITY: To define the GET request for checking the status of operations like beneficiary creation or update.
// INPUTS: Request ID (string).
// OUTPUTS: CounterpartyRequestStatusData (DTO).
*/
namespace Apoloz\AlfaBank\Requests\NominalAccounts;
// <SECTION name="module_imports" intent="Import DTO and Saloon components.">
// <BELIEF_STATE "This request requires the `CounterpartyRequestStatusData` DTO for its response.">
use Apoloz\AlfaBank\Data\NominalAccounts\CounterpartyRequestStatusData;
use Saloon\Enums\Method;
use Saloon\Http\Request;
use Saloon\Http\Response;
// </SECTION>
// <SECTION name="class_definition" intent="Define the request to get the status of a counterparty operation.">
// <BELIEF_STATE "This class allows for polling the status of long-running operations, which is common in banking APIs where processes are not instant.">
class GetCounterpartyRequestStatusRequest extends Request
{
// <SECTION name="http_method" intent="Declare the HTTP verb.">
// <BELIEF_STATE "Retrieving the status of a resource is a read-only operation, making GET the correct verb.">
protected Method $method = Method::GET;
// </SECTION>
// <SECTION name="constructor" intent="Inject the unique request ID.">
// <BELIEF_STATE "The `requestId` is mandatory to identify the specific operation whose status is being queried.">
public function __construct(
protected string $requestId
) {}
// </SECTION>
// <SECTION name="endpoint_resolver" intent="Construct the request URI for the counterparty request status.">
// <BELIEF_STATE "The endpoint is dynamically constructed with the `requestId` to target the specific status resource.">
public function resolveEndpoint(): string
{
return "/api/na/jp/v1/beneficiaries/requests/{$this->requestId}/status";
}
// </SECTION>
// <SECTION name="response_caster" intent="Map the JSON response to a CounterpartyRequestStatusData DTO.">
// <BELIEF_STATE "Casting the response to a `CounterpartyRequestStatusData` DTO provides a clear, type-safe representation of the asynchronous request's current state.">
public function createDtoFromResponse(Response $response): CounterpartyRequestStatusData
{
return CounterpartyRequestStatusData::from($response->json());
}
// </SECTION>
}

28
src/Requests/NominalAccounts/GetNominalAccountsRequest.php
View File

@@ -1,8 +1,16 @@
<?php
/*
// MODULE_CONTRACT: Represents the API call to retrieve a list of nominal accounts.
// RESPONSIBILITY: To define the GET request for fetching all available nominal accounts.
// INPUTS: None (implicitly uses connector's authentication).
// OUTPUTS: A collection of NominalAccountData DTOs.
*/
namespace Apoloz\AlfaBank\Requests\NominalAccounts;
// <SECTION name="module_imports" intent="Import DTO and Saloon components.">
// <BELIEF_STATE "This request requires the `NominalAccountData` DTO for its response, within a `DataCollection`.">
use Apoloz\AlfaBank\Data\NominalAccounts\NominalAccountData;
use Apoloz\AlfaBank\Traits\HasAlfaPagination;
use Saloon\Enums\Method;
use Saloon\Http\Request;
use Saloon\Http\Response;
@@ -10,15 +18,33 @@ use Spatie\LaravelData\DataCollection;
class GetNominalAccountsRequest extends Request
{
use HasAlfaPagination;
protected Method $method = Method::GET;
public function __construct(
?int $limit = 100,
?int $offset = 0
) {
$this->limit = $limit;
$this->offset = $offset;
}
public function resolveEndpoint(): string
{
return '/api/na/jp/v1/nominal-accounts';
}
protected function defaultQuery(): array
{
return $this->getPaginationQuery();
}
// <SECTION name="response_caster" intent="Map the JSON array response to a collection of DTOs.">
// <BELIEF_STATE "The API returns a JSON array of accounts. Using `NominalAccountData::collect` automatically converts this array into a type-safe, iterable `DataCollection` of `NominalAccountData` objects.">
public function createDtoFromResponse(Response $response): DataCollection
{
return NominalAccountData::collect($response->json(), DataCollection::class);
}
// </SECTION>
}

24
src/Requests/NominalAccounts/Identification/GetIdentifyStatusRequest.php
View File

@@ -1,28 +1,50 @@
<?php
/*
// MODULE_CONTRACT: Represents the API call to retrieve the status of a transaction identification request.
// RESPONSIBILITY: To define the GET request for checking the outcome of a previously initiated identification process.
// INPUTS: Unidentified transaction ID and the specific identification request ID.
// OUTPUTS: IdentifyResponseData (DTO).
*/
namespace Apoloz\AlfaBank\Requests\NominalAccounts\Identification;
// <SECTION name="module_imports" intent="Import DTO and Saloon components.">
// <BELIEF_STATE "This request requires the `IdentifyResponseData` DTO for its response.">
use Apoloz\AlfaBank\Data\NominalAccounts\Identification\IdentifyResponseData;
use Saloon\Enums\Method;
use Saloon\Http\Request;
use Saloon\Http\Response;
// </SECTION>
// <SECTION name="class_definition" intent="Define the request to get the status of an identification operation.">
// <BELIEF_STATE "This class allows polling for the status of an asynchronous identification process, common in systems where processing takes time.">
class GetIdentifyStatusRequest extends Request
{
// <SECTION name="http_method" intent="Declare the HTTP verb.">
// <BELIEF_STATE "Retrieving the status of a resource is a read-only operation, making GET the correct verb.">
protected Method $method = Method::GET;
// </SECTION>
// <SECTION name="constructor" intent="Inject the transaction ID and the identification request ID.">
// <BELIEF_STATE "Both `id` and `identifyId` are mandatory path parameters to pinpoint the specific status resource.">
public function __construct(
protected string $id,
protected string $identifyId
) {}
// </SECTION>
// <SECTION name="endpoint_resolver" intent="Construct the request URI for the identification status.">
// <BELIEF_STATE "The endpoint is dynamically constructed, targeting the status of a specific identification request for a given unidentified transaction.">
public function resolveEndpoint(): string
{
return "/api/na/jp/v1/unidentified-transactions/{$this->id}/identify/{$this->identifyId}";
}
// </SECTION>
// <SECTION name="response_caster" intent="Map the JSON response to an IdentifyResponseData DTO.">
// <BELIEF_STATE "Casting the response to an `IdentifyResponseData` DTO provides a clear, type-safe object representing the current status of the identification process.">
public function createDtoFromResponse(Response $response): IdentifyResponseData
{
return IdentifyResponseData::from($response->json());
}
// </SECTION>
}

27
src/Requests/NominalAccounts/Identification/GetUnidentifiedTransactionsRequest.php
View File

@@ -1,27 +1,48 @@
<?php
/*
// MODULE_CONTRACT: Represents the API call to retrieve a list of unidentified transactions.
// RESPONSIBILITY: To define the GET request for fetching transactions that need to be identified or categorized.
// INPUTS: Account number, and optional pagination parameters.
// OUTPUTS: UnidentifiedTransactionCollectionData (DTO).
*/
namespace Apoloz\AlfaBank\Requests\NominalAccounts\Identification;
// <SECTION name="module_imports" intent="Import DTO and Saloon components.">
// <BELIEF_STATE "This request requires the `UnidentifiedTransactionCollectionData` DTO for its response.">
use Apoloz\AlfaBank\Data\NominalAccounts\Identification\UnidentifiedTransactionCollectionData;
use Saloon\Enums\Method;
use Saloon\Http\Request;
use Saloon\Http\Response;
// </SECTION>
// <SECTION name="class_definition" intent="Define the request to get a list of unidentified transactions.">
// <BELIEF_STATE "This class encapsulates the query for transactions that require manual or automated identification, crucial for managing nominal accounts.">
class GetUnidentifiedTransactionsRequest extends Request
{
// <SECTION name="http_method" intent="Declare the HTTP verb.">
// <BELIEF_STATE "Retrieving a collection of resources is a read-only operation, making GET the correct verb.">
protected Method $method = Method::GET;
// </SECTION>
// <SECTION name="constructor" intent="Inject the required account number and optional pagination parameters.">
// <BELIEF_STATE "The `accountNumber` is mandatory to specify which account's unidentified transactions are being queried. Pagination parameters (`limit`, `offset`) allow for efficient retrieval of large datasets.">
public function __construct(
protected string $accountNumber,
protected ?int $limit = null,
protected ?int $offset = null,
) {}
// </SECTION>
// <SECTION name="endpoint_resolver" intent="Define the URI for the unidentified transactions collection.">
// <BELIEF_STATE "The endpoint is a static URI for fetching unidentified transactions.">
public function resolveEndpoint(): string
{
return '/api/na/jp/v1/unidentified-transactions';
}
// </SECTION>
// <SECTION name="query_builder" intent="Construct the query string from the provided parameters.">
// <BELIEF_STATE "Using `array_filter` ensures that only non-null optional parameters are included in the query string, resulting in clean and valid API requests.">
protected function defaultQuery(): array
{
return array_filter([
@@ -30,9 +51,13 @@ class GetUnidentifiedTransactionsRequest extends Request
'offset' => $this->offset,
]);
}
// </SECTION>
// <SECTION name="response_caster" intent="Map the JSON response to a collection DTO.">
// <BELIEF_STATE "Casting the response to an `UnidentifiedTransactionCollectionData` DTO provides a type-safe, iterable object for the list of transactions awaiting identification.">
public function createDtoFromResponse(Response $response): UnidentifiedTransactionCollectionData
{
return UnidentifiedTransactionCollectionData::from($response->json());
}
// </SECTION>
}

27
src/Requests/NominalAccounts/Identification/IdentifyTransactionRequest.php
View File

@@ -1,7 +1,14 @@
<?php
/*
// MODULE_CONTRACT: Represents the API call to identify (categorize/assign) an unidentified transaction.
// RESPONSIBILITY: To define the POST request for assigning an identified entity to a previously unidentified transaction.
// INPUTS: Unidentified transaction ID, and an IdentifyRequestData DTO.
// OUTPUTS: IdentifyResponseData (DTO).
*/
namespace Apoloz\AlfaBank\Requests\NominalAccounts\Identification;
// <SECTION name="module_imports" intent="Import DTOs and Saloon components for a JSON body request.">
// <BELIEF_STATE "This POST request needs specific DTOs for its JSON body and its response, along with Saloon's body-handling traits.">
use Apoloz\AlfaBank\Data\NominalAccounts\Identification\IdentifyRequestData;
use Apoloz\AlfaBank\Data\NominalAccounts\Identification\IdentifyResponseData;
use Saloon\Contracts\Body\HasBody;
@@ -9,30 +16,48 @@ use Saloon\Enums\Method;
use Saloon\Http\Request;
use Saloon\Http\Response;
use Saloon\Traits\Body\HasJsonBody;
// </SECTION>
// <SECTION name="class_definition" intent="Define the request to identify an unidentified transaction.">
// <BELIEF_STATE "This class encapsulates the action of categorizing a transaction, which is a state-changing operation.">
class IdentifyTransactionRequest extends Request implements HasBody
{
use HasJsonBody;
// <SECTION name="http_method" intent="Declare the HTTP verb.">
// <BELIEF_STATE "Triggering an action or a new process to identify a transaction is correctly represented by the POST verb.">
protected Method $method = Method::POST;
// </SECTION>
// <SECTION name="constructor" intent="Inject the transaction ID and the identification data.">
// <BELIEF_STATE "The constructor takes the unique `id` of the unidentified transaction and the `IdentifyRequestData` DTO, ensuring all necessary information for identification is provided.">
public function __construct(
protected string $id,
protected IdentifyRequestData $data
) {}
// </SECTION>
// <SECTION name="endpoint_resolver" intent="Construct the request URI for identifying a transaction.">
// <BELIEF_STATE "The endpoint is specific to performing an `identify` action on a given `unidentified-transactions` resource.">
public function resolveEndpoint(): string
{
return "/api/na/jp/v1/unidentified-transactions/{$this->id}/identify";
}
// </SECTION>
// <SECTION name="body_builder" intent="Serialize the DTO for the request body.">
// <BELIEF_STATE "Delegating serialization to the DTO's `toArray` method ensures the payload is correctly formatted for the API.">
protected function defaultBody(): array
{
return $this->data->toArray();
}
// </SECTION>
// <SECTION name="response_caster" intent="Map the JSON response to an IdentifyResponseData DTO.">
// <BELIEF_STATE "The API returns an `IdentifyResponseData` DTO, providing a type-safe object representing the outcome of the identification process.">
public function createDtoFromResponse(Response $response): IdentifyResponseData
{
return IdentifyResponseData::from($response->json());
}
// </SECTION>
}

27
src/Requests/NominalAccounts/Identification/RefundUnidentifiedTransactionRequest.php
View File

@@ -1,7 +1,14 @@
<?php
/*
// MODULE_CONTRACT: Represents the API call to refund an unidentified transaction.
// RESPONSIBILITY: To define the POST request for initiating a refund for an unidentified transaction.
// INPUTS: Unidentified transaction ID, and RefundUnidentifiedTransactionRequestData DTO.
// OUTPUTS: RefundUnidentifiedTransactionResponseData (DTO).
*/
namespace Apoloz\AlfaBank\Requests\NominalAccounts\Identification;
// <SECTION name="module_imports" intent="Import DTOs and Saloon components for a JSON body request.">
// <BELIEF_STATE "This POST request requires specific DTOs for its JSON body and its response, along with Saloon's body-handling traits.">
use Apoloz\AlfaBank\Data\NominalAccounts\Identification\RefundUnidentifiedTransactionRequestData;
use Apoloz\AlfaBank\Data\NominalAccounts\Identification\RefundUnidentifiedTransactionResponseData;
use Saloon\Contracts\Body\HasBody;
@@ -9,30 +16,48 @@ use Saloon\Enums\Method;
use Saloon\Http\Request;
use Saloon\Http\Response;
use Saloon\Traits\Body\HasJsonBody;
// </SECTION>
// <SECTION name="class_definition" intent="Define the request to refund an unidentified transaction.">
// <BELIEF_STATE "This class encapsulates the action of refunding a transaction, which is a state-changing operation.">
class RefundUnidentifiedTransactionRequest extends Request implements HasBody
{
use HasJsonBody;
// <SECTION name="http_method" intent="Declare the HTTP verb.">
// <BELIEF_STATE "Initiating a refund is a new action that changes the system state, so POST is the correct verb.">
protected Method $method = Method::POST;
// </SECTION>
// <SECTION name="constructor" intent="Inject the transaction ID and the refund data.">
// <BELIEF_STATE "The constructor takes the unique `id` of the unidentified transaction and the `RefundUnidentifiedTransactionRequestData` DTO, ensuring all necessary information for the refund is provided.">
public function __construct(
protected string $id,
protected RefundUnidentifiedTransactionRequestData $data
) {}
// </SECTION>
// <SECTION name="endpoint_resolver" intent="Construct the request URI for refunding a transaction.">
// <BELIEF_STATE "The endpoint is specific to performing a `refunds` action on a given `unidentified-transactions` resource.">
public function resolveEndpoint(): string
{
return "/api/na/jp/v1/unidentified-transactions/{$this->id}/refunds";
}
// </SECTION>
// <SECTION name="body_builder" intent="Serialize the DTO for the request body.">
// <BELIEF_STATE "Delegating serialization to the DTO's `toArray` method ensures the payload is correctly formatted for the API.">
protected function defaultBody(): array
{
return $this->data->toArray();
}
// </SECTION>
// <SECTION name="response_caster" intent="Map the JSON response to a RefundUnidentifiedTransactionResponseData DTO.">
// <BELIEF_STATE "The API returns a `RefundUnidentifiedTransactionResponseData` DTO, providing a type-safe object representing the outcome of the refund process.">
public function createDtoFromResponse(Response $response): RefundUnidentifiedTransactionResponseData
{
return RefundUnidentifiedTransactionResponseData::from($response->json());
}
// </SECTION>
}

27
src/Requests/NominalAccounts/Payouts/CreatePayoffRequest.php
View File

@@ -1,7 +1,14 @@
<?php
/*
// MODULE_CONTRACT: Represents the API call to create a new payoff for a nominal account.
// RESPONSIBILITY: To define the POST request for initiating a payment (payoff) from a nominal account.
// INPUTS: PayoffRequestData DTO.
// OUTPUTS: PayoffResponseData DTO.
*/
namespace Apoloz\AlfaBank\Requests\NominalAccounts\Payouts;
// <SECTION name="module_imports" intent="Import DTOs and Saloon components for a JSON body request.">
// <BELIEF_STATE "This POST request needs specific DTOs for its JSON body and its response, along with Saloon's body-handling traits.">
use Apoloz\AlfaBank\Data\NominalAccounts\Payouts\PayoffRequestData;
use Apoloz\AlfaBank\Data\NominalAccounts\Payouts\PayoffResponseData;
use Saloon\Contracts\Body\HasBody;
@@ -9,29 +16,47 @@ use Saloon\Enums\Method;
use Saloon\Http\Request;
use Saloon\Http\Response;
use Saloon\Traits\Body\HasJsonBody;
// </SECTION>
// <SECTION name="class_definition" intent="Define the request to create a payoff.">
// <BELIEF_STATE "This class encapsulates the critical action of initiating a payment, ensuring type safety and clear definition of the request.">
class CreatePayoffRequest extends Request implements HasBody
{
use HasJsonBody;
// <SECTION name="http_method" intent="Declare the HTTP verb.">
// <BELIEF_STATE "Creating a new payment resource or initiating a payment action is correctly represented by the POST verb.">
protected Method $method = Method::POST;
// </SECTION>
// <SECTION name="constructor" intent="Inject the DTO containing the payoff details.">
// <BELIEF_STATE "Using a strongly-typed `PayoffRequestData` DTO ensures that all necessary payment information is provided and correctly structured before the request is sent.">
public function __construct(
protected PayoffRequestData $data
) {}
// </SECTION>
// <SECTION name="endpoint_resolver" intent="Define the URI for creating payoffs.">
// <BELIEF_STATE "The endpoint is a static URI for initiating payoffs from nominal accounts.">
public function resolveEndpoint(): string
{
return '/api/na/jp/v1/payoffs';
}
// </SECTION>
// <SECTION name="body_builder" intent="Serialize the DTO for the request body.">
// <BELIEF_STATE "Delegating serialization to the DTO's `toArray` method ensures the complex payment payload is correctly formatted for the API.">
protected function defaultBody(): array
{
return $this->data->toArray();
}
// </SECTION>
// <SECTION name="response_caster" intent="Map the JSON response to a PayoffResponseData DTO.">
// <BELIEF_STATE "The API returns a `PayoffResponseData` DTO, providing a type-safe object representing the outcome of the payoff creation, typically including a request ID and status.">
public function createDtoFromResponse(Response $response): PayoffResponseData
{
return PayoffResponseData::from($response->json());
}
// </SECTION>
}

27
src/Requests/NominalAccounts/Payouts/CreateTaxRefundRequest.php
View File

@@ -1,7 +1,14 @@
<?php
/*
// MODULE_CONTRACT: Represents the API call to create a new tax refund request.
// RESPONSIBILITY: To define the POST request for initiating a tax refund payment.
// INPUTS: TaxRefundRequestData DTO.
// OUTPUTS: TaxRefundResponseData DTO.
*/
namespace Apoloz\AlfaBank\Requests\NominalAccounts\Payouts;
// <SECTION name="module_imports" intent="Import DTOs and Saloon components for a JSON body request.">
// <BELIEF_STATE "This POST request needs specific DTOs for its JSON body and its response, along with Saloon's body-handling traits.">
use Apoloz\AlfaBank\Data\NominalAccounts\Payouts\TaxRefundRequestData;
use Apoloz\AlfaBank\Data\NominalAccounts\Payouts\TaxRefundResponseData;
use Saloon\Contracts\Body\HasBody;
@@ -9,29 +16,47 @@ use Saloon\Enums\Method;
use Saloon\Http\Request;
use Saloon\Http\Response;
use Saloon\Traits\Body\HasJsonBody;
// </SECTION>
// <SECTION name="class_definition" intent="Define the request to create a tax refund.">
// <BELIEF_STATE "This class encapsulates the critical action of initiating a tax refund payment, ensuring type safety and clear definition of the request.">
class CreateTaxRefundRequest extends Request implements HasBody
{
use HasJsonBody;
// <SECTION name="http_method" intent="Declare the HTTP verb.">
// <BELIEF_STATE "Creating a new refund resource or initiating a refund action is correctly represented by the POST verb.">
protected Method $method = Method::POST;
// </SECTION>
// <SECTION name="constructor" intent="Inject the DTO containing the tax refund details.">
// <BELIEF_STATE "Using a strongly-typed `TaxRefundRequestData` DTO ensures that all necessary refund information is provided and correctly structured before the request is sent.">
public function __construct(
protected TaxRefundRequestData $data
) {}
// </SECTION>
// <SECTION name="endpoint_resolver" intent="Define the URI for creating tax refunds.">
// <BELIEF_STATE "The endpoint is a static URI for initiating tax refunds.">
public function resolveEndpoint(): string
{
return '/api/na/jp/v1/tax-refund';
}
// </SECTION>
// <SECTION name="body_builder" intent="Serialize the DTO for the request body.">
// <BELIEF_STATE "Delegating serialization to the DTO's `toArray` method ensures the complex refund payload is correctly formatted for the API.">
protected function defaultBody(): array
{
return $this->data->toArray();
}
// </SECTION>
// <SECTION name="response_caster" intent="Map the JSON response to a TaxRefundResponseData DTO.">
// <BELIEF_STATE "The API returns a `TaxRefundResponseData` DTO, providing a type-safe object representing the outcome of the tax refund creation, typically including a request ID and status.">
public function createDtoFromResponse(Response $response): TaxRefundResponseData
{
return TaxRefundResponseData::from($response->json());
}
// </SECTION>
}

24
src/Requests/NominalAccounts/Payouts/GetPayoffRequest.php
View File

@@ -1,27 +1,49 @@
<?php
/*
// MODULE_CONTRACT: Represents the API call to retrieve details of a specific payoff.
// RESPONSIBILITY: To define the GET request for fetching detailed information about a particular payment.
// INPUTS: Payoff ID (string).
// OUTPUTS: DetailedPayoffData (DTO).
*/
namespace Apoloz\AlfaBank\Requests\NominalAccounts\Payouts;
// <SECTION name="module_imports" intent="Import DTO and Saloon components.">
// <BELIEF_STATE "This request requires the `DetailedPayoffData` DTO for its comprehensive response.">
use Apoloz\AlfaBank\Data\NominalAccounts\Payouts\DetailedPayoffData;
use Saloon\Enums\Method;
use Saloon\Http\Request;
use Saloon\Http\Response;
// </SECTION>
// <SECTION name="class_definition" intent="Define the request to get details of a payoff.">
// <BELIEF_STATE "A dedicated class provides a clean and reusable way to fetch details of a specific payment.">
class GetPayoffRequest extends Request
{
// <SECTION name="http_method" intent="Declare the HTTP verb.">
// <BELIEF_STATE "Retrieving a specific resource by its ID is a read-only operation, making GET the correct RESTful verb.">
protected Method $method = Method::GET;
// </SECTION>
// <SECTION name="constructor" intent="Inject the payoff's unique identifier.">
// <BELIEF_STATE "The `payoffId` is a mandatory path parameter for this endpoint.">
public function __construct(
protected string $payoffId
) {}
// </SECTION>
// <SECTION name="endpoint_resolver" intent="Construct the request URI with the dynamic payoff ID.">
// <BELIEF_STATE "The endpoint is dynamically constructed with the `payoffId` to target the specific payment resource.">
public function resolveEndpoint(): string
{
return "/api/na/jp/v1/payoffs/{$this->payoffId}";
}
// </SECTION>
// <SECTION name="response_caster" intent="Map the JSON response to a DetailedPayoffData DTO.">
// <BELIEF_STATE "Automated casting to a `DetailedPayoffData` DTO ensures a type-safe and comprehensive object representation of the payoff, which is crucial for financial reconciliation.">
public function createDtoFromResponse(Response $response): DetailedPayoffData
{
return DetailedPayoffData::from($response->json());
}
// </SECTION>
}

24
src/Requests/NominalAccounts/Payouts/GetPayoffStatusRequest.php
View File

@@ -1,27 +1,49 @@
<?php
/*
// MODULE_CONTRACT: Represents the API call to retrieve the status of a specific payoff.
// RESPONSIBILITY: To define the GET request for checking the current status of a payment.
// INPUTS: Payoff ID (string).
// OUTPUTS: PayoffResponseData (DTO).
*/
namespace Apoloz\AlfaBank\Requests\NominalAccounts\Payouts;
// <SECTION name="module_imports" intent="Import DTO and Saloon components.">
// <BELIEF_STATE "This request requires the `PayoffResponseData` DTO for its response.">
use Apoloz\AlfaBank\Data\NominalAccounts\Payouts\PayoffResponseData;
use Saloon\Enums\Method;
use Saloon\Http\Request;
use Saloon\Http\Response;
// </SECTION>
// <SECTION name="class_definition" intent="Define the request to get the status of a payoff.">
// <BELIEF_STATE "This class allows polling for the status of an asynchronous payment process, which is critical for tracking financial transactions.">
class GetPayoffStatusRequest extends Request
{
// <SECTION name="http_method" intent="Declare the HTTP verb.">
// <BELIEF_STATE "Retrieving the status of a resource is a read-only operation, making GET the correct verb.">
protected Method $method = Method::GET;
// </SECTION>
// <SECTION name="constructor" intent="Inject the payoff's unique identifier.">
// <BELIEF_STATE "The `payoffId` is a mandatory path parameter to identify the specific payment whose status is being queried.">
public function __construct(
protected string $payoffId
) {}
// </SECTION>
// <SECTION name="endpoint_resolver" intent="Construct the request URI for the payoff status.">
// <BELIEF_STATE "The endpoint is dynamically constructed with the `payoffId` to target the specific payment status resource.">
public function resolveEndpoint(): string
{
return "/api/na/jp/v1/payoffs/{$this->payoffId}/status";
}
// </SECTION>
// <SECTION name="response_caster" intent="Map the JSON response to a PayoffResponseData DTO.">
// <BELIEF_STATE "Casting the response to a `PayoffResponseData` DTO provides a clear, type-safe object representing the current state of the payment.">
public function createDtoFromResponse(Response $response): PayoffResponseData
{
return PayoffResponseData::from($response->json());
}
// </SECTION>
}

24
src/Requests/NominalAccounts/Payouts/GetTaxRefundStatusRequest.php
View File

@@ -1,27 +1,49 @@
<?php
/*
// MODULE_CONTRACT: Represents the API call to retrieve the status of a specific tax refund request.
// RESPONSIBILITY: To define the GET request for checking the current status of a tax refund.
// INPUTS: Tax refund ID (string).
// OUTPUTS: TaxRefundResponseData (DTO).
*/
namespace Apoloz\AlfaBank\Requests\NominalAccounts\Payouts;
// <SECTION name="module_imports" intent="Import DTO and Saloon components.">
// <BELIEF_STATE "This request requires the `TaxRefundResponseData` DTO for its response.">
use Apoloz\AlfaBank\Data\NominalAccounts\Payouts\TaxRefundResponseData;
use Saloon\Enums\Method;
use Saloon\Http\Request;
use Saloon\Http\Response;
// </SECTION>
// <SECTION name="class_definition" intent="Define the request to get the status of a tax refund.">
// <BELIEF_STATE "This class allows polling for the status of an asynchronous tax refund process, which is critical for financial tracking.">
class GetTaxRefundStatusRequest extends Request
{
// <SECTION name="http_method" intent="Declare the HTTP verb.">
// <BELIEF_STATE "Retrieving the status of a resource is a read-only operation, making GET the correct verb.">
protected Method $method = Method::GET;
// </SECTION>
// <SECTION name="constructor" intent="Inject the tax refund's unique identifier.">
// <BELIEF_STATE "The `taxRefundId` is a mandatory path parameter to identify the specific refund whose status is being queried.">
public function __construct(
protected string $taxRefundId
) {}
// </SECTION>
// <SECTION name="endpoint_resolver" intent="Construct the request URI for the tax refund status.">
// <BELIEF_STATE "The endpoint is dynamically constructed with the `taxRefundId` to target the specific refund status resource.">
public function resolveEndpoint(): string
{
return "/api/na/jp/v1/tax-refund/{$this->taxRefundId}/status";
}
// </SECTION>
// <SECTION name="response_caster" intent="Map the JSON response to a TaxRefundResponseData DTO.">
// <BELIEF_STATE "Casting the response to a `TaxRefundResponseData` DTO provides a clear, type-safe object representing the current state of the tax refund.">
public function createDtoFromResponse(Response $response): TaxRefundResponseData
{
return TaxRefundResponseData::from($response->json());
}
// </SECTION>
}

27
src/Requests/NominalAccounts/Payouts/PayoffAcceptRequest.php
View File

@@ -1,38 +1,63 @@
<?php
/*
// MODULE_CONTRACT: Represents the API call to accept or reject a pending payoff.
// RESPONSIBILITY: To define the PATCH request for changing the status of a payoff (approve/decline).
// INPUTS: Payoff ID (string) and a boolean indicating acceptance.
// OUTPUTS: Boolean (true if successful, false otherwise).
*/
namespace Apoloz\AlfaBank\Requests\NominalAccounts\Payouts;
// <SECTION name="module_imports" intent="Import Saloon components for a JSON body request.">
// <BELIEF_STATE "This PATCH request requires body-handling traits because it sends a JSON payload.">
use Saloon\Contracts\Body\HasBody;
use Saloon\Enums\Method;
use Saloon\Http\Request;
use Saloon\Http\Response;
use Saloon\Traits\Body\HasJsonBody;
// </SECTION>
// <SECTION name="class_definition" intent="Define the request to accept a payoff.">
// <BELIEF_STATE "This class encapsulates a critical state-changing operation on a payment.">
class PayoffAcceptRequest extends Request implements HasBody
{
use HasJsonBody;
// <SECTION name="http_method" intent="Declare the HTTP verb.">
// <BELIEF_STATE "PATCH is the appropriate verb for partially modifying an existing resource's state, such as accepting or rejecting a payoff.">
protected Method $method = Method::PATCH;
// </SECTION>
// <SECTION name="constructor" intent="Inject the payoff ID and the acceptance flag.">
// <BELIEF_STATE "The constructor requires the `payoffId` to target the specific payment and an `accept` flag to indicate the desired action. The default `true` simplifies the most common use case (accept).">
public function __construct(
protected string $payoffId,
protected bool $accept = true
) {}
// </SECTION>
// <SECTION name="endpoint_resolver" intent="Construct the request URI for accepting a payoff.">
// <BELIEF_STATE "The endpoint is specific to the `/accept` action on a given payoff resource.">
public function resolveEndpoint(): string
{
return "/api/na/jp/v1/payoffs/{$this->payoffId}/accept";
}
// </SECTION>
// <SECTION name="body_builder" intent="Construct the JSON body for the request.">
// <BELIEF_STATE "The request body is simple, containing only the `accept` boolean flag.">
protected function defaultBody(): array
{
return [
'accept' => $this->accept,
];
}
// </SECTION>
// <SECTION name="response_caster" intent="Extract the boolean result from the JSON response.">
// <BELIEF_STATE "The API returns a JSON object, but the relevant information is a boolean status. This method extracts that boolean, providing a direct, simple result to the user.">
public function createDtoFromResponse(Response $response): bool
{
return (bool)($response->json('result') ?? false);
}
// </SECTION>
}

27
src/Requests/NominalAccounts/Payouts/TaxRefundAcceptRequest.php
View File

@@ -1,36 +1,61 @@
<?php
/*
// MODULE_CONTRACT: Represents the API call to accept a pending tax refund request.
// RESPONSIBILITY: To define the PATCH request for approving a tax refund payment.
// INPUTS: Tax refund ID (string) and a boolean indicating acceptance.
// OUTPUTS: Boolean (true if successful, false otherwise).
*/
namespace Apoloz\AlfaBank\Requests\NominalAccounts\Payouts;
// <SECTION name="module_imports" intent="Import Saloon components for a JSON body request.">
// <BELIEF_STATE "This PATCH request requires body-handling traits because it sends a JSON payload.">
use Saloon\Contracts\Body\HasBody;
use Saloon\Enums\Method;
use Saloon\Http\Request;
use Saloon\Http\Response;
use Saloon\Traits\Body\HasJsonBody;
// </SECTION>
// <SECTION name="class_definition" intent="Define the request to accept a tax refund.">
// <BELIEF_STATE "This class encapsulates a critical state-changing operation for tax refunds.">
class TaxRefundAcceptRequest extends Request implements HasBody
{
use HasJsonBody;
// <SECTION name="http_method" intent="Declare the HTTP verb.">
// <BELIEF_STATE "PATCH is the appropriate verb for partially modifying an existing resource's state, such as accepting a tax refund.">
protected Method $method = Method::PATCH;
// </SECTION>
// <SECTION name="constructor" intent="Inject the tax refund ID and the acceptance flag.">
// <BELIEF_STATE "The constructor requires the `taxRefundId` to target the specific refund and an `accept` flag to indicate the desired action.">
public function __construct(
protected string $taxRefundId,
protected bool $accept
) {}
// </SECTION>
// <SECTION name="endpoint_resolver" intent="Construct the request URI for accepting a tax refund.">
// <BELIEF_STATE "The endpoint is specific to the `/accept` action on a given tax refund resource.">
public function resolveEndpoint(): string
{
return "/api/na/jp/v1/tax-refund/{$this->taxRefundId}/accept";
}
// </SECTION>
// <SECTION name="query_builder" intent="Construct the query string for the acceptance status.">
// <BELIEF_STATE "The API expects the acceptance status as a query parameter, represented as 'true' or 'false' strings.">
protected function defaultQuery(): array
{
return ['accept' => $this->accept ? 'true' : 'false'];
}
// </SECTION>
// <SECTION name="response_caster" intent="Extract the boolean result from the JSON response.">
// <BELIEF_STATE "The API returns a JSON object, but the relevant information for this operation is a boolean status. This method extracts that boolean, providing a direct, simple result to the user.">
public function createDtoFromResponse(Response $response): bool
{
return (bool)($response->json('result') ?? false);
}
// </SECTION>
}

26
src/Requests/NominalAccounts/UniversalRecipients/CreateUniversalRecipientRequest.php
View File

@@ -1,7 +1,15 @@
<?php
/*
// MODULE_CONTRACT: Represents the API call to create a new universal recipient.
// RESPONSIBILITY: To define the POST request for registering a universal recipient.
// INPUTS: CreateUniversalRecipientRequestData DTO.
// OUTPUTS: UniversalRecipientResponseData DTO.
*/
namespace Apoloz\AlfaBank\Requests\NominalAccounts\UniversalRecipients;
// <SECTION name="module_imports" intent="Import DTOs and Saloon components for a JSON body request.">
// <BELIEF_STATE "This POST request requires specific DTOs for its JSON body and its response, along with Saloon's body-handling traits.">
use Apoloz\AlfaBank\Data\NominalAccounts\UniversalRecipients\CreateUniversalRecipientRequestData;
use Apoloz\AlfaBank\Data\NominalAccounts\UniversalRecipients\UniversalRecipientResponseData;
use Saloon\Contracts\Body\HasBody;
@@ -9,29 +17,47 @@ use Saloon\Enums\Method;
use Saloon\Http\Request;
use Saloon\Http\Response;
use Saloon\Traits\Body\HasJsonBody;
// </SECTION>
// <SECTION name="class_definition" intent="Define the request to create a new universal recipient.">
// <BELIEF_STATE "A dedicated class for universal recipient creation improves code organization and reusability.">
class CreateUniversalRecipientRequest extends Request implements HasBody
{
use HasJsonBody;
// <SECTION name="http_method" intent="Declare the HTTP verb.">
// <BELIEF_STATE "Creating a new universal recipient resource is correctly represented by the POST verb.">
protected Method $method = Method::POST;
// </SECTION>
// <SECTION name="constructor" intent="Inject the DTO containing the new universal recipient's data.">
// <BELIEF_STATE "Using a strongly-typed DTO for the payload enforces data integrity and makes the request's dependencies clear.">
public function __construct(
protected CreateUniversalRecipientRequestData $data
) {}
// </SECTION>
// <SECTION name="endpoint_resolver" intent="Define the URI for the universal recipients collection.">
// <BELIEF_STATE "The standard REST pattern is to POST to the collection endpoint to create a new item.">
public function resolveEndpoint(): string
{
return '/api/na/jp/v1/universal-recipients';
}
// </SECTION>
// <SECTION name="body_builder" intent="Serialize the DTO for the request body.">
// <BELIEF_STATE "Delegating serialization to the DTO's `toArray` method decouples the request from the DTO's internal structure.">
protected function defaultBody(): array
{
return $this->data->toArray();
}
// </SECTION>
// <SECTION name="response_caster" intent="Map the JSON response to a DTO.">
// <BELIEF_STATE "Casting the response to a `UniversalRecipientResponseData` DTO provides a type-safe object representing the result of the creation.">
public function createDtoFromResponse(Response $response): UniversalRecipientResponseData
{
return UniversalRecipientResponseData::from($response->json());
}
// </SECTION>
}

23
src/Requests/NominalAccounts/UniversalRecipients/GetUniversalRecipientRequest.php
View File

@@ -1,27 +1,50 @@
<?php
/*
// MODULE_CONTRACT: Represents the API call to retrieve a single universal recipient by its ID.
// RESPONSIBILITY: To define the GET request structure for fetching a specific universal recipient's details.
// INPUTS: Universal recipient ID (string).
// OUTPUTS: UniversalRecipientData (DTO).
*/
namespace Apoloz\AlfaBank\Requests\NominalAccounts\UniversalRecipients;
// <SECTION name="module_imports" intent="Import DTO and Saloon components.">
// <BELIEF_STATE "This request needs the `UniversalRecipientData` DTO for its response and Saloon's base Request class.">
use Apoloz\AlfaBank\Data\NominalAccounts\UniversalRecipients\UniversalRecipientData;
use Saloon\Enums\Method;
use Saloon\Http\Request;
use Saloon\Http\Response;
// </SECTION>
// <SECTION name="class_definition" intent="Define the request to get a single universal recipient.">
// <BELIEF_STATE "A dedicated class encapsulates the logic for this specific API endpoint, promoting reusability and separation of concerns.">
class GetUniversalRecipientRequest extends Request
{
// <SECTION name="http_method" intent="Declare the HTTP verb.">
// <BELIEF_STATE "Fetching a resource by its identifier is a read-only operation, making GET the correct RESTful verb.">
protected Method $method = Method::GET;
// </SECTION>
// <SECTION name="constructor" intent="Inject the universal recipient's unique identifier.">
// <BELIEF_STATE "The `universalRecipientId` is a mandatory path parameter for this endpoint, so it must be required in the constructor.">
public function __construct(
protected string $universalRecipientId
) {}
// </SECTION>
// <SECTION name="endpoint_resolver" intent="Construct the request URI with the dynamic universal recipient ID.">
// <BELIEF_STATE "The endpoint is dynamic. Injecting the `universalRecipientId` into the URI is handled here to keep the endpoint definition clean and centralized within the request class.">
public function resolveEndpoint(): string
{
return "/api/na/jp/v1/universal-recipients/{$this->universalRecipientId}";
}
// </SECTION>
// <SECTION name="response_caster" intent="Map the JSON response to a UniversalRecipientData DTO.">
// <BELIEF_STATE "Automated casting to a DTO provides type safety and a clean object-oriented interface for the API response.">
public function createDtoFromResponse(Response $response): UniversalRecipientData
{
return UniversalRecipientData::from($response->json());
}
// </SECTION>
}

26
src/Requests/NominalAccounts/UniversalRecipients/GetUniversalRecipientsRequest.php
View File

@@ -1,17 +1,33 @@
<?php
/*
// MODULE_CONTRACT: Represents the API call to retrieve a list of universal recipients.
// RESPONSIBILITY: To define the GET request for fetching a filtered, paginated list of universal recipients.
// INPUTS: Account number, type, and various optional filters.
// OUTPUTS: A collection of UniversalRecipientData DTOs.
*/
namespace Apoloz\AlfaBank\Requests\NominalAccounts\UniversalRecipients;
// <SECTION name="module_imports" intent="Import DTOs and Saloon components.">
// <BELIEF_STATE "This request returns a collection of `UniversalRecipientData` DTOs.">
use Apoloz\AlfaBank\Data\NominalAccounts\UniversalRecipients\UniversalRecipientData;
use Saloon\Enums\Method;
use Saloon\Http\Request;
use Saloon\Http\Response;
use Spatie\LaravelData\DataCollection;
// </SECTION>
// <SECTION name="class_definition" intent="Define the request to get a list of universal recipients.">
// <BELIEF_STATE "This class encapsulates a complex query with multiple optional filters, simplifying its use.">
class GetUniversalRecipientsRequest extends Request
{
// <SECTION name="http_method" intent="Declare the HTTP verb.">
// <BELIEF_STATE "GET is the correct verb for retrieving a collection of resources.">
protected Method $method = Method::GET;
// </SECTION>
// <SECTION name="constructor" intent="Inject required filters and optional pagination parameters.">
// <BELIEF_STATE "The `accountNumber` and `type` are mandatory filters. Other fields are optional filters or pagination parameters, allowing for flexible querying.">
public function __construct(
protected string $accountNumber,
protected string $type,
@@ -20,12 +36,18 @@ class GetUniversalRecipientsRequest extends Request
protected ?bool $isActive = null,
protected ?string $date = null,
) {}
// </SECTION>
// <SECTION name="endpoint_resolver" intent="Define the URI for the universal recipients collection.">
// <BELIEF_STATE "The endpoint is the static collection URI; all filters are applied via query parameters.">
public function resolveEndpoint(): string
{
return '/api/na/jp/v1/universal-recipients';
}
// </SECTION>
// <SECTION name="query_builder" intent="Construct the query string from the provided filters.">
// <BELIEF_STATE "Using `array_filter` is a robust way to build the query array, as it automatically omits any optional parameters that were not provided (i.e., are `null`), resulting in a clean URL.">
protected function defaultQuery(): array
{
return array_filter([
@@ -37,9 +59,13 @@ class GetUniversalRecipientsRequest extends Request
'date' => $this->date,
], fn($val) => $val !== null);
}
// </SECTION>
// <SECTION name="response_caster" intent="Map the JSON response to a collection DTO.">
// <BELIEF_STATE "Casting the response to a `DataCollection` of `UniversalRecipientData` provides a type-safe, iterable object. The specific API response structure requires extracting from the `universalRecipients` key.">
public function createDtoFromResponse(Response $response): DataCollection
{
return UniversalRecipientData::collect($response->json('universalRecipients'), DataCollection::class);
}
// </SECTION>
}

26
src/Requests/NominalAccounts/UniversalRecipients/Requisites/AddUniversalRecipientRequisiteRequest.php
View File

@@ -1,7 +1,15 @@
<?php
/*
// MODULE_CONTRACT: Represents the API call to add a new requisite to a universal recipient.
// RESPONSIBILITY: To define the POST request for registering a new payment requisite for a universal recipient.
// INPUTS: Universal recipient ID, and a CreateRequisiteRequestData DTO.
// OUTPUTS: RequisiteData (DTO) of the newly added requisite.
*/
namespace Apoloz\AlfaBank\Requests\NominalAccounts\UniversalRecipients\Requisites;
// <SECTION name="module_imports" intent="Import DTOs and Saloon components for a JSON body request.">
// <BELIEF_STATE "This POST request requires specific DTOs for its JSON body and its response, along with Saloon's body-handling traits. It reuses `CreateRequisiteRequestData` from the Beneficiaries module.">
use Apoloz\AlfaBank\Data\NominalAccounts\Beneficiaries\Requisites\CreateRequisiteRequestData;
use Apoloz\AlfaBank\Data\NominalAccounts\Beneficiaries\Requisites\RequisiteData;
use Saloon\Contracts\Body\HasBody;
@@ -9,30 +17,48 @@ use Saloon\Enums\Method;
use Saloon\Http\Request;
use Saloon\Http\Response;
use Saloon\Traits\Body\HasJsonBody;
// </SECTION>
// <SECTION name="class_definition" intent="Define the request to add a requisite to a universal recipient.">
// <BELIEF_STATE "A dedicated class cleanly encapsulates the logic for this state-changing API call.">
class AddUniversalRecipientRequisiteRequest extends Request implements HasBody
{
use HasJsonBody;
// <SECTION name="http_method" intent="Declare the HTTP verb.">
// <BELIEF_STATE "Adding a new sub-resource (requisite) to an existing resource (universal recipient) is typically a POST operation to the sub-resource collection.">
protected Method $method = Method::POST;
// </SECTION>
// <SECTION name="constructor" intent="Inject the universal recipient ID and the requisite data.">
// <BELIEF_STATE "The `universalRecipientId` is a mandatory path parameter, and `CreateRequisiteRequestData` ensures the payload is type-safe and valid.">
public function __construct(
protected string $universalRecipientId,
protected CreateRequisiteRequestData $data
) {}
// </SECTION>
// <SECTION name="endpoint_resolver" intent="Construct the request URI for adding a requisite.">
// <BELIEF_STATE "The endpoint targets the `requisites` sub-resource of a specific universal recipient.">
public function resolveEndpoint(): string
{
return "/api/na/jp/v1/universal-recipients/{$this->universalRecipientId}/requisites";
}
// </SECTION>
// <SECTION name="body_builder" intent="Serialize the DTO for the request body.">
// <BELIEF_STATE "Delegating serialization to the DTO's `toArray` method ensures the payload is correctly formatted for the API.">
protected function defaultBody(): array
{
return $this->data->toArray();
}
// </SECTION>
// <SECTION name="response_caster" intent="Map the JSON response to a RequisiteData DTO.">
// <BELIEF_STATE "The API returns the newly created requisite object. Casting it to a DTO provides a clean, type-safe object for the user.">
public function createDtoFromResponse(Response $response): RequisiteData
{
return RequisiteData::from($response->json());
}
// </SECTION>
}

23
src/Requests/NominalAccounts/UniversalRecipients/Requisites/GetUniversalRecipientRequisitesRequest.php
View File

@@ -1,28 +1,51 @@
<?php
/*
// MODULE_CONTRACT: Represents the API call to retrieve all requisites for a specific universal recipient.
// RESPONSIBILITY: To define the GET request for fetching payment requisites associated with a universal recipient.
// INPUTS: Universal recipient ID (string).
// OUTPUTS: A collection of RequisiteData DTOs.
*/
namespace Apoloz\AlfaBank\Requests\NominalAccounts\UniversalRecipients\Requisites;
// <SECTION name="module_imports" intent="Import DTO and Saloon components.">
// <BELIEF_STATE "This request returns a collection of `RequisiteData` DTOs.">
use Apoloz\AlfaBank\Data\NominalAccounts\Beneficiaries\Requisites\RequisiteData;
use Saloon\Enums\Method;
use Saloon\Http\Request;
use Saloon\Http\Response;
use Spatie\LaravelData\DataCollection;
// </SECTION>
// <SECTION name="class_definition" intent="Define the request to get requisites for a universal recipient.">
// <BELIEF_STATE "This class encapsulates the logic for fetching all requisites related to a specific universal recipient.">
class GetUniversalRecipientRequisitesRequest extends Request
{
// <SECTION name="http_method" intent="Declare the HTTP verb.">
// <BELIEF_STATE "GET is the correct verb for retrieving a collection of resources.">
protected Method $method = Method::GET;
// </SECTION>
// <SECTION name="constructor" intent="Inject the universal recipient's unique identifier.">
// <BELIEF_STATE "The `universalRecipientId` is mandatory to specify which universal recipient's requisites are being queried.">
public function __construct(
protected string $universalRecipientId
) {}
// </SECTION>
// <SECTION name="endpoint_resolver" intent="Construct the request URI for universal recipient requisites.">
// <BELIEF_STATE "The endpoint targets the `requisites` sub-resource of a specific universal recipient.">
public function resolveEndpoint(): string
{
return "/api/na/jp/v1/universal-recipients/{$this->universalRecipientId}/requisites";
}
// </SECTION>
// <SECTION name="response_caster" intent="Map the JSON array response to a collection of DTOs.">
// <BELIEF_STATE "The API returns a JSON array. Using `RequisiteData::collect` automatically converts this array into a type-safe, iterable `DataCollection` of `RequisiteData` objects.">
public function createDtoFromResponse(Response $response): DataCollection
{
return RequisiteData::collect($response->json(), DataCollection::class);
}
// </SECTION>
}

24
src/Requests/NominalAccounts/UniversalRecipients/Requisites/UpdateUniversalRecipientRequisiteRequest.php
View File

@@ -1,32 +1,46 @@
<?php
/*
// MODULE_CONTRACT: Represents the API call to update a specific requisite for a universal recipient.
// RESPONSIBILITY: To define the PATCH request for modifying an existing payment requisite.
// INPUTS: Universal recipient ID, requisite ID, and an UpdateRequisiteRequestData DTO.
// OUTPUTS: No specific DTO, typically a 200 OK or 202 Accepted status.
*/
namespace Apoloz\AlfaBank\Requests\NominalAccounts\UniversalRecipients\Requisites;
use Apoloz\AlfaBank\Data\NominalAccounts\Beneficiaries\Requisites\UpdateRequisiteRequestData;
// <SECTION name="module_imports" intent="Import DTO and Saloon components for a JSON body request.">
// <BELIEF_STATE "This PATCH request requires the `UpdateRequisiteRequestData` DTO for its JSON body and Saloon's body-handling traits.">
use Apoloz\AlfaBank\Data\Shared\GeneralStatusData;
use Saloon\Contracts\Body\HasBody;
use Saloon\Enums\Method;
use Saloon\Http\Request;
use Saloon\Http\Response;
use Saloon\Traits\Body\HasJsonBody;
class UpdateUniversalRecipientRequisiteRequest extends Request implements HasBody
{
use HasJsonBody;
protected Method $method = Method::PATCH;
protected Method $method = Method::PUT;
public function __construct(
protected string $universalRecipientId,
protected string $requisiteId,
protected UpdateRequisiteRequestData $data
protected array $data
) {}
public function resolveEndpoint(): string
{
return "/api/na/jp/v1/universal-recipients/{$this->universalRecipientId}/requisites/{$this->requisiteId}";
return "/api/na/jp/v1/universal-recipients/{$this->universalRecipientId}/requisites/{$this->universalRecipientId}";
}
protected function defaultBody(): array
{
return $this->data->toArray();
return $this->data;
}
public function createDtoFromResponse(Response $response): GeneralStatusData
{
return GeneralStatusData::from(['success' => $response->successful()]);
}
}