Update documentation and examples, add new nominal accounts features and authentication methods

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

src/Core/AlfaBankConnector.php

@@ -9,8 +9,9 @@ namespace Apoloz\AlfaBank\Core;
 use Apoloz\AlfaBank\Contracts\SignerInterface;
 use Apoloz\AlfaBank\Http\Middleware\RequestIdMiddleware;
 use Apoloz\AlfaBank\Http\Pagination\AlfaOffsetPaginator;
-use Apoloz\AlfaBank\Requests\Auth\GetTokenRequest;
+use Apoloz\AlfaBank\Requests\Auth\GetTokenRequest; // Will be removed
 use Apoloz\AlfaBank\Traits\HasAlfaErrorHandling;
+use Saloon\Helpers\OAuth2\OAuthConfig;
 use Saloon\Http\Connector;
 use Saloon\Http\Request;
 use Saloon\PaginationPlugin\Contracts\HasPagination;
@@ -18,13 +19,17 @@ use Saloon\PaginationPlugin\OffsetPaginator;
 use Saloon\Traits\Plugins\AlwaysThrowOnErrors;
 use Saloon\Traits\RequestProperties\HasTries;
 use Saloon\Traits\Plugins\HasTimeout;
+use Saloon\Contracts\OAuth2\OAuth2Api;
+use Saloon\Traits\OAuth2\AuthorizationCodeGrant;
+use Apoloz\AlfaBank\Enums\Environment;
 
-class AlfaBankConnector extends Connector implements HasPagination
+class AlfaBankConnector extends Connector implements HasPagination, OAuth2Api
 {
     use HasTimeout;
     use HasTries;
     use AlwaysThrowOnErrors;
     use HasAlfaErrorHandling;
+    use AuthorizationCodeGrant;
 
     public function __construct(
         protected AlfaConfig $alfaConfig,
@@ -39,6 +44,20 @@ class AlfaBankConnector extends Connector implements HasPagination
         return $this->alfaConfig->baseUrl;
     }
 
+    protected function resolveOauth2Config(): OAuthConfig
+    {
+        $idUrl = $this->alfaConfig->baseUrl === Environment::PRODUCTION->value
+            ? Environment::ID_PRODUCTION->value
+            : Environment::ID_SANDBOX->value;
+
+        return OAuthConfig::make()
+            ->setClientId($this->alfaConfig->clientId ?? '')
+            ->setClientSecret($this->alfaConfig->clientSecret ?? '')
+            ->setRedirectUri($this->alfaConfig->redirectUri ?? '')
+            ->setAuthorizeEndpoint($idUrl . '/oidc/authorize')
+            ->setTokenEndpoint('/oidc/token');
+    }
+
     protected function defaultConfig(): array
     {
         $config = [
@@ -79,55 +98,7 @@ class AlfaBankConnector extends Connector implements HasPagination
         return new AlfaOffsetPaginator($this, $request);
     }
 
-    /**
-     * Exchange Authorization Code for tokens (H2H Flow).
-     */
-    public function authWithCode(string $code, string $redirectUri): \Apoloz\AlfaBank\Data\Auth\TokenData
-    {
-        if (!$this->alfaConfig->clientId || !$this->alfaConfig->clientSecret) {
-             throw new \RuntimeException("Client ID/Secret not configured.");
-        }
-
-        $request = new GetTokenRequest(
-            clientId: $this->alfaConfig->clientId,
-            clientSecret: $this->alfaConfig->clientSecret,
-            code: $code,
-            redirectUri: $redirectUri,
-            grantType: 'authorization_code'
-        );
-
-        $response = $this->send($request);
-        $data = $response->dto();
-
-        $this->authenticate(new \Saloon\Http\Auth\TokenAuthenticator($data->access_token));
-        
-        return $data;
-    }
-
-    /**
-     * Refresh access token using refresh token.
-     */
-    public function refreshToken(string $refreshToken): \Apoloz\AlfaBank\Data\Auth\TokenData
-    {
-        if (!$this->alfaConfig->clientId || !$this->alfaConfig->clientSecret) {
-             throw new \RuntimeException("Client ID/Secret not configured.");
-        }
-
-        $request = new GetTokenRequest(
-            clientId: $this->alfaConfig->clientId,
-            clientSecret: $this->alfaConfig->clientSecret,
-            refreshToken: $refreshToken,
-            grantType: 'refresh_token'
-        );
-
-        $response = $this->send($request);
-        $data = $response->dto();
-
-        $this->authenticate(new \Saloon\Http\Auth\TokenAuthenticator($data->access_token));
-
-        return $data;
-    }
-
+    // login() kept for ClientCredentials compatibility (legacy/simple flow)
     public function login(?string $clientId = null, ?string $clientSecret = null): static
     {
         // Allow overriding config via method arguments
@@ -144,9 +115,6 @@ class AlfaBankConnector extends Connector implements HasPagination
             grantType: 'client_credentials'
         );
 
-        // Send request (using self to reuse cert/ssl config)
-        // We temporarily disable auth middleware if we had any, 
-        // but here we are raw, so it's fine.
         $response = $this->send($request);
         $data = $response->dto();
 
@@ -155,6 +123,7 @@ class AlfaBankConnector extends Connector implements HasPagination
         return $this;
     }
     // </SECTION>
+    // </SECTION>
     
     // <SECTION name="signer_accessor" intent="Provide access to the configured signing service for requests that require a digital signature.">
     // <BELIEF_STATE "Requests should not instantiate their own signing logic. The connector acts as a service locator, providing the globally-configured Signer service. This ensures that all signatures are generated consistently.">