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

Co-authored-by: Qwen-Coder <qwen-coder@alibabacloud.com>
2026-01-24 17:18:59 +03:00
parent 2964c391b5
commit bb5f91d399
13 changed files with 290 additions and 157 deletions
--- a/examples/16_automated_startup.php
+++ b/examples/16_automated_startup.php
@@ -0,0 +1,89 @@
+<?php
+
+declare(strict_types=1);
+
+require_once __DIR__ . '/vendor/autoload.php';
+
+use Apoloz\AlfaBank\AlfaBank;
+use Apoloz\AlfaBank\Requests\Auth\RefreshClientSecretRequest;
+use Apoloz\AlfaBank\Requests\NominalAccounts\Beneficiaries\GetBeneficiariesRequest;
+use Apoloz\AlfaBank\Enums\Environment;
+
+/**
+ * FULLY AUTOMATED WORKFLOW
+ * 
+ * Scenario: You don't want to store `client_secret` persistently. 
+ * Instead, you use your Certificates to fetch a fresh secret on startup (or when needed),
+ * and then immediately use it to refresh your OAuth tokens.
+ * 
+ * CAUTION: Requesting a new secret invalidates the old one. 
+ * If you have multiple app instances, implement a shared cache (Redis/DB) for the secret!
+ */
+
+// --- CONFIGURATION ---
+// You only need immutable identifiers and certificates.
+$clientId = getenv('ALFA_BAAS_CLIENT_ID');
+$redirectUri = 'https://your-app.com/callback';
+$certPath = __DIR__ . '/certs/client.cer';
+$keyPath  = __DIR__ . '/certs/private.key';
+$accNum   = '40702810...'; 
+
+// This assumes you have already passed the browser flow once and saved the refresh token.
+$savedRefreshToken = 'your_saved_refresh_token_from_db';
+
+// 1. Initialize Bare Connector (mTLS only)
+$baas = AlfaBank::baas($certPath, $keyPath, Environment::SANDBOX);
+
+try {
+    // 2. FETCH CLIENT SECRET DYNAMICALLY
+    // We prove our identity via mTLS certificates.
+    echo "1. Requesting dynamic client_secret via API...\n";
+    
+    // In a real app: CHECK CACHE FIRST!
+    // $cachedSecret = Cache::get('alfa_client_secret');
+    // if ($cachedSecret) { $tempSecret = $cachedSecret; } else { ... }
+    
+    $secretResponse = $baas->send(new RefreshClientSecretRequest($clientId));
+    $tempSecret = $secretResponse->dto()->clientSecret;
+    
+    echo "   Secret acquired: " . substr($tempSecret, 0, 5) . "...\n";
+
+    // 3. AUTHENTICATE OAUTH2
+    // Now we use the fresh secret to get an access token.
+    echo "2. Refreshing OAuth2 session...\n";
+    
+    // Re-initialize connector with the new secret
+    $baasReady = AlfaBank::baas(
+        certificatePath: $certPath,
+        privateKeyPath: $keyPath,
+        environment: Environment::SANDBOX,
+        clientId: $clientId,
+        clientSecret: $tempSecret,
+        redirectUri: $redirectUri
+    );
+
+    // Refresh token using native method
+    $authenticator = $baasReady->refreshAccessToken($savedRefreshToken);
+    $baasReady->authenticate($authenticator);
+    
+    echo "   Session active. Access Token expires at " . $authenticator->getExpiresAt()->format('H:i:s') . "\n";
+    
+    // Update DB if refresh token rotated
+    if ($authenticator->getRefreshToken()) {
+        // saveNewRefreshToken($authenticator->getRefreshToken());
+        echo "   New Refresh Token saved.\n";
+    }
+
+    // 4. BUSINESS LOGIC
+    echo "3. Fetching beneficiaries...\n";
+    
+    $response = $baasReady->send(new GetBeneficiariesRequest($accNum, 'FL_RESIDENT'));
+    
+    echo "   Success! Found " . count($response->dto()->beneficiaries) . " records.\n";
+
+} catch (Exception $e) {
+    echo "CRITICAL ERROR: " . $e->getMessage() . "\n";
+    if (method_exists($e, 'getResponse')) {
+        echo "Body: " . $e->getResponse()->body() . "\n";
+    }
+}