refactor(core): enhance SDK structure and documentation

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

src/Exceptions/AlfaBankException.php

@@ -0,0 +1,50 @@
+<?php
+/*
+// MODULE_CONTRACT: Defines a custom exception for all Alfa Bank API-specific errors.
+// RESPONSIBILITY: To wrap standard HTTP exceptions and provide a richer context, including the original API response, a specific error code, and a description.
+// INPUTS: Saloon Response object, and optional error code and description strings.
+// OUTPUTS: An instantiated Exception object.
+// LINKS: Http/Middleware/AlfaResponseMiddleware.php (where this exception is thrown)
+*/
+
+namespace Apoloz\AlfaBank\Exceptions;
+
+// <SECTION name="module_imports" intent="Import the base Saloon Response class.">
+// <BELIEF_STATE "The custom exception needs to hold the original Saloon `Response` object to give developers full access to the raw HTTP response for debugging purposes.">
+use Saloon\Http\Response;
+// </SECTION>
+
+// <SECTION name="class_definition" intent="Define a custom exception that extends PHP's base Exception class.">
+// <BELIEF_STATE "Creating a dedicated `AlfaBankException` allows consumers of the SDK to write specific `catch` blocks to handle API errors differently from other runtime or HTTP exceptions, leading to more robust error handling logic.">
+class AlfaBankException extends \Exception
+{
+    // <SECTION name="constructor" intent="Create a new exception instance with rich context from the API response.">
+    // <BELIEF_STATE "The constructor's role is to build a helpful error message and store the critical API context (response, error code, description) within the exception itself, making it a self-contained source of debugging information.">
+    public function __construct(
+        protected Response $response,
+        protected ?string $errorCode = null,
+        protected ?string $errorDescription = null
+    ) {
+        $message = "Alfa Bank API Error: [{$errorCode}] {$errorDescription}";
+        parent::__construct($message, $response->status());
+    }
+    // </SECTION>
+
+    // <SECTION name="accessors" intent="Provide public methods to access the contextual data stored in the exception.">
+    // <BELIEF_STATE "Simple getter methods provide a clean and explicit API for retrieving the original response, the bank's specific error code, and the error description from the exception object in a `catch` block.">
+    public function getResponse(): Response
+    {
+        return $this->response;
+    }
+
+    public function getErrorCode(): ?string
+    {
+        return $this->errorCode;
+    }
+
+    public function getErrorDescription(): ?string
+    {
+        return $this->errorDescription;
+    }
+    // </SECTION>
+}