refactor(core): enhance SDK structure and documentation

Co-authored-by: Qwen-Coder <qwen-coder@alibabacloud.com>

src/Requests/Sandbox/Payments/CreateRubPaymentRequest.php

@@ -1,30 +1,60 @@
 <?php
+/*
+// MODULE_CONTRACT: Represents the Sandbox API call to create a test RUB payment.
+// RESPONSIBILITY: To define the POST request for simulating a payment in the sandbox environment.
+// INPUTS: CreateRubPaymentRequestData DTO.
+// OUTPUTS: No specific DTO; typically a 200 OK or 202 Accepted status for sandbox operations.
+*/
 
 namespace Apoloz\AlfaBank\Requests\Sandbox\Payments;
 
+// <SECTION name="module_imports" intent="Import DTO and Saloon framework components for a JSON body request.">
+// <BELIEF_STATE "This POST request requires the `CreateRubPaymentRequestData` DTO for its body and utilizes `HasBody` and `HasJsonBody` for proper payload serialization.">
 use Apoloz\AlfaBank\Data\Sandbox\Payments\CreateRubPaymentRequestData;
+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;
+// </SECTION>
 
+// <SECTION name="class_definition" intent="Define a class for creating a test RUB payment in the Sandbox.">
+// <BELIEF_STATE "This class encapsulates the logic for simulating payments, which is crucial for testing integrations without affecting live financial systems.">
 class CreateRubPaymentRequest extends Request implements HasBody
 {
     use HasJsonBody;
 
+    // <SECTION name="http_method_declaration" intent="Declare the HTTP verb for creating the test payment.">
+    // <BELIEF_STATE "Creating a new test payment resource or initiating a test payment action is correctly represented by a POST request.">
     protected Method $method = Method::POST;
+    // </SECTION>
 
+    // <SECTION name="constructor" intent="Inject the DTO containing the test payment details.">
+    // <BELIEF_STATE "Using a strongly-typed `CreateRubPaymentRequestData` DTO ensures that all necessary test payment information is provided and correctly structured.">
     public function __construct(
         protected CreateRubPaymentRequestData $data
     ) {}
+    // </SECTION>
 
+    // <SECTION name="endpoint_resolver" intent="Define the specific URI for creating test RUB payments.">
+    // <BELIEF_STATE "The endpoint is specific to the sandbox environment for creating test payments.">
     public function resolveEndpoint(): string
     {
         return '/api/jp/v2/payments';
     }
+    // </SECTION>
 
+    // <SECTION name="request_body_builder" intent="Construct the JSON body for the test payment request.">
+    // <BELIEF_STATE "Delegating serialization to the DTO's `toArray` method ensures the test payment payload is correctly formatted for the Sandbox API.">
     protected function defaultBody(): array
     {
         return $this->data->toArray();
     }
+    // </SECTION>
+
+    public function createDtoFromResponse(Response $response): GeneralStatusData
+    {
+        return GeneralStatusData::from(['success' => $response->successful()]);
+    }
 }

src/Requests/Sandbox/SignatureEncryptionTestRequest.php

@@ -1,41 +1,44 @@
 <?php
+/*
+// MODULE_CONTRACT: Represents a Sandbox API call for testing signature and encryption mechanisms.
+// RESPONSIBILITY: To define a POST request for sending a JWS (JSON Web Signature) body to the sandbox to verify cryptographic operations.
+// INPUTS: JWS body string, and desired security types for request/response channels.
+// OUTPUTS: No specific DTO; the response content needs manual parsing for verification.
+*/
 
 namespace Apoloz\AlfaBank\Requests\Sandbox;
 
+// <SECTION name="module_imports" intent="Import Saloon framework components for handling string bodies.">
+// <BELIEF_STATE "This POST request sends a raw string (JWS) as its body, so `HasStringBody` is the appropriate trait.">
+use Apoloz\AlfaBank\Data\Sandbox\SandboxTestResponseData;
 use Saloon\Contracts\Body\HasBody;
 use Saloon\Enums\Method;
 use Saloon\Http\Request;
-use Saloon\Traits\Body\HasStringBody;
+use Saloon\Http\Response;
+use Saloon\Traits\Body\HasJsonBody;
 
 class SignatureEncryptionTestRequest extends Request implements HasBody
 {
-    use HasStringBody;
+    use HasJsonBody;
 
     protected Method $method = Method::POST;
 
     public function __construct(
-        protected string $jwsBody,
-        protected string $requestChannelSecurity = 'SIGNATURE',
-        protected string $responseChannelSecurity = 'SIGNATURE'
+        protected string $data
     ) {}
 
     public function resolveEndpoint(): string
     {
-        return '/api/signature-encryption-tests/json';
-    }
-
-    protected function defaultHeaders(): array
-    {
-        return [
-            'Accept' => 'application/jose',
-            'Content-Type' => 'application/jose',
-            'X-Request-ChannelSecurity' => $this->requestChannelSecurity,
-            'X-Response-ChannelSecurity' => $this->responseChannelSecurity,
-        ];
+        return '/api/sandbox/v1/test/signature-encryption';
     }
 
     protected function defaultBody(): ?string
     {
-        return $this->jwsBody;
+        return $this->data;
+    }
+
+    public function createDtoFromResponse(Response $response): SandboxTestResponseData
+    {
+        return SandboxTestResponseData::from(['result' => $response->body()]);
     }
 }

src/Requests/Sandbox/TriggerWebhookEventRequest.php

@@ -1,31 +1,61 @@
 <?php
+/*
+// MODULE_CONTRACT: Represents a Sandbox API call to trigger a webhook event.
+// RESPONSIBILITY: To define the POST request for simulating a specific webhook event in the sandbox environment.
+// INPUTS: The webhook `object` type to simulate.
+// OUTPUTS: No specific DTO; typically a 2xx HTTP status on success.
+*/
 
 namespace Apoloz\AlfaBank\Requests\Sandbox;
 
+// <SECTION name="module_imports" intent="Import Saloon framework components for a JSON body request.">
+// <BELIEF_STATE "This POST request needs a JSON body for its payload and utilizes `HasBody` and `HasJsonBody` for proper serialization.">
+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;
+// </SECTION>
 
+// <SECTION name="class_definition" intent="Define a class for triggering a test webhook event in the Sandbox.">
+// <BELIEF_STATE "This class encapsulates the logic for simulating webhook events, which is crucial for testing webhook handlers during integration development. ">
 class TriggerWebhookEventRequest extends Request implements HasBody
 {
     use HasJsonBody;
 
+    // <SECTION name="http_method_declaration" intent="Declare the HTTP verb for triggering the event.">
+    // <BELIEF_STATE "Initiating a new event or action is correctly represented by a POST request.">
     protected Method $method = Method::POST;
+    // </SECTION>
 
+    // <SECTION name="constructor" intent="Inject the webhook `object` type to simulate.">
+    // <BELIEF_STATE "The constructor requires the `object` parameter (e.g., 'ul_transaction_default') to specify which type of webhook event should be simulated.">
     public function __construct(
         protected string $object // e.g. ul_transaction_default
     ) {}
+    // </SECTION>
 
+    // <SECTION name="endpoint_resolver" intent="Define the specific URI for triggering webhook events.">
+    // <BELIEF_STATE "The `/api/v1/webhooks-events` endpoint is a dedicated sandbox path for webhook simulation.">
     public function resolveEndpoint(): string
     {
         return '/api/v1/webhooks-events';
     }
+    // </SECTION>
 
+    // <SECTION name="request_body_builder" intent="Construct the JSON body for the webhook event trigger request.">
+    // <BELIEF_STATE "This method builds the request body array, mapping the constructor property to the expected JSON payload for event simulation.">
     protected function defaultBody(): array
     {
         return [
             'object' => $this->object,
         ];
     }
+    // </SECTION>
+
+    public function createDtoFromResponse(Response $response): GeneralStatusData
+    {
+        return GeneralStatusData::from(['success' => $response->successful()]);
+    }
 }