refactor(core): enhance SDK structure and documentation

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

examples/01_baas_flow.php

@@ -0,0 +1,40 @@
+<?php
+
+require_once __DIR__ . '/../vendor/autoload.php';
+
+use Apoloz\AlfaBank\AlfaBank;
+use Apoloz\AlfaBank\Enums\Environment;
+
+// 1. Initialize
+// Ensure you have valid certificates for the Sandbox
+$baas = AlfaBank::baas(
+    certificatePath: __DIR__ . '/certs/client.cer',
+    privateKeyPath: __DIR__ . '/certs/private.key',
+    environment: Environment::SANDBOX,
+    caBundlePath: __DIR__ . '/certs/russian_trusted_sub_ca.crt' // Mincifry
+);
+
+try {
+    echo "Authenticating...\n";
+    $baas->login(
+        clientId: 'your-client-id',
+        clientSecret: 'your-client-secret'
+    );
+    echo "Authentication Successful!\n";
+
+    // 2. Create a Beneficiary (Counterparty)
+    echo "Creating Beneficiary...\n";
+    
+    // In a real app, use the DTOs
+    // $payload = new CreateBeneficiaryRequestData(...);
+    // $baas->send(new CreateBeneficiaryRequest($payload));
+    
+    echo "Beneficiary Request Sent (Mock).\n";
+
+} catch (\Exception $e) {
+    echo "Error: " . $e->getMessage() . "\n";
+    if ($e instanceof \Apoloz\AlfaBank\Exceptions\AlfaBankException) {
+        echo "API Code: " . $e->getErrorCode() . "\n";
+    }
+}
+

examples/02_sbp_qr.php

@@ -0,0 +1,45 @@
+<?php
+
+require_once __DIR__ . '/../vendor/autoload.php';
+
+use Apoloz\AlfaBank\AlfaBank;
+use Apoloz\AlfaBank\Enums\Environment;
+use Apoloz\AlfaBank\Sbp\Requests\GetQrCodeRequest;
+use Apoloz\AlfaBank\Sbp\Data\QrCodeRequestData;
+
+// 1. Initialize SBP
+$sbp = AlfaBank::sbp(
+    certificatePath: __DIR__ . '/certs/client.cer',
+    privateKeyPath: __DIR__ . '/certs/private.key',
+    keyNameAlias: 'my-alias', // Required for SBP signatures in some contexts
+    environment: Environment::SANDBOX
+);
+
+try {
+    echo "Generating Static QR Code...\n";
+
+    $payload = new QrCodeRequestData(
+        termNo: 'TEST_TERM_001',
+        qrcType: '01', // Static
+        amount: '15000', // 150.00 RUB
+        paymentPurpose: 'Test Payment'
+    );
+
+    $request = new GetQrCodeRequest($payload);
+    $response = $sbp->send($request);
+
+    if ($response->successful()) {
+        $qrData = $response->dto();
+        echo "QR Payload: " . $qrData->payload . "\n";
+        echo "QR Image URL: " . $qrData->image . "\n";
+    } else {
+        echo "Failed to generate QR.\n";
+    }
+
+    // Example of Pagination (if supported by SBP endpoints)
+    // $paginator = $sbp->paginate(new SomeSbpListRequest());
+    // foreach($paginator as $item) { ... }
+
+} catch (\Exception $e) {
+    echo "Error: " . $e->getMessage() . "\n";
+}

examples/03_sandbox_init.php

@@ -0,0 +1,55 @@
+<?php
+
+require_once __DIR__ . '/../vendor/autoload.php';
+
+use Apoloz\AlfaBank\AlfaBank;
+use Apoloz\AlfaBank\Enums\Environment;
+
+/**
+ * This example shows how to initialize the SDK with the Sandbox files provided by the bank.
+ * 
+ * IMPORTANT: You must first convert the .pfx file to .pem format using OpenSSL:
+ * 
+ * 1. Extract signing key: 
+ *    openssl pkcs12 -in certificate_for_requests_sign_with_password_1234.pfx -nocerts -out signing_key.pem -nodes -password pass:1234
+ * 
+ * 2. Extract signing certificate:
+ *    openssl pkcs12 -in certificate_for_requests_sign_with_password_1234.pfx -clcerts -nokeys -out signing_cert.pem -password pass:1234
+ * 
+ * 3. Ensure transport certs are in PEM format if they aren't already.
+ */
+
+// --- 1. BaaS / Main API Initialization ---
+$baas = AlfaBank::baas(
+    // Transport (mTLS) - use the sandbox_cert/key files
+    certificatePath: __DIR__ . '/certs/sandbox_cert_2026.cer', 
+    privateKeyPath: __DIR__ . '/certs/sandbox_key_2026.key',
+    
+    // Signing (Business Logic) - use the extracted PEM files from PFX
+    signingCertificatePath: __DIR__ . '/certs/signing_cert.pem',
+    signingPrivateKeyPath: __DIR__ . '/certs/signing_key.pem',
+    
+    environment: Environment::SANDBOX,
+    caBundlePath: __DIR__ . '/certs/apica_2022_chain.cer' // Trust chain
+);
+
+echo "BaaS Connector Initialized.\n";
+
+
+// --- 2. SBP (Faster Payments) Initialization ---
+$sbp = AlfaBank::sbp(
+    // SBP usually uses its own mTLS pair found in the sbp_payout/mtls folder
+    certificatePath: __DIR__ . '/certs/sbp_payout/mtls/9728109955_test_mtls.crt',
+    privateKeyPath: __DIR__ . '/certs/sbp_payout/mtls/9728109955_test_mtls.key',
+    
+    // Terminal ID from terminal_num.txt
+    keyNameAlias: '9728109955', 
+    
+    environment: Environment::SANDBOX,
+    caBundlePath: __DIR__ . '/certs/sbp_payout/sandbox_root/root-ca-test.crt'
+);
+
+echo "SBP Connector Initialized.\n";
+
+// Now you can use $baas->login(...) or $sbp->send(...)
+

examples/04_nominal_accounts.php

@@ -0,0 +1,54 @@
+<?php
+
+require_once __DIR__ . '/../vendor/autoload.php';
+
+use Apoloz\AlfaBank\AlfaBank;
+use Apoloz\AlfaBank\Enums\Environment;
+use Apoloz\AlfaBank\Requests\NominalAccounts\Beneficiaries\CreateBeneficiaryRequest;
+use Apoloz\AlfaBank\Data\NominalAccounts\Beneficiaries\CreateBeneficiaryRequestData;
+use Apoloz\AlfaBank\Data\NominalAccounts\Beneficiaries\AddressData;
+use Apoloz\AlfaBank\Data\NominalAccounts\Payouts\DigestSignatureData;
+use Spatie\LaravelData\DataCollection;
+
+/**
+ * Example: Creating a Beneficiary for a Nominal Account.
+ * This flow requires a digital signature (CMS).
+ */
+
+$baas = AlfaBank::baas(
+    certificatePath: 'path/to/cert.pem',
+    privateKeyPath: 'path/to/key.pem',
+    environment: Environment::SANDBOX
+);
+
+// 1. Prepare beneficiary data
+$payload = new CreateBeneficiaryRequestData(
+    type: 'FL_RESIDENT',
+    countryOfTaxResidence: 'RU',
+    name: 'Ivanov Ivan Ivanovich',
+    inn: '771234567890',
+    addresses: AddressData::collect([
+        [
+            'type' => 'REGISTRATION_ADDRESS',
+            'address' => 'Moscow, Lenina st, 10',
+            'country' => 'RU'
+        ]
+    ], DataCollection::class),
+    digestSignatures: DigestSignatureData::collect([
+        [
+            'base64Encoded' => 'MOCK_SIGNATURE', // In real life, use CmsSigner::sign()
+            'signatureType' => 'cms'
+        ]
+    ], DataCollection::class)
+);
+
+// 2. Login and send request
+$baas->login('client-id', 'client-secret');
+$response = $baas->send(new CreateBeneficiaryRequest($payload));
+
+if ($response->successful()) {
+    $data = $response->dto(); // BeneficiaryResponseData
+    echo "Beneficiary creation accepted. ID: {$data->id}, Status: {$data->status}\n";
+} else {
+    echo "Error: " . $response->body() . "\n";
+}

examples/05_webhooks.php

@@ -0,0 +1,49 @@
+<?php
+
+require_once __DIR__ . '/../vendor/autoload.php';
+
+use Apoloz\AlfaBank\AlfaBank;
+use Apoloz\AlfaBank\Webhooks\WebhookFactory;
+use Apoloz\AlfaBank\Requests\Webhooks\GetWebhooksRequest;
+use Apoloz\AlfaBank\Requests\Webhooks\CreateWebhookRequest;
+use Apoloz\AlfaBank\Data\Webhooks\Subscriptions\WebhookSubscriptionRequestData;
+
+/**
+ * 1. Managing Webhooks (BaaS API)
+ */
+$baas = AlfaBank::baas('cert.pem', 'key.pem');
+$baas->login('id', 'secret');
+
+// List existing webhooks
+$response = $baas->send(new GetWebhooksRequest());
+$webhooks = $response->dto(); // DataCollection of WebhookSubscriptionData
+
+foreach ($webhooks as $webhook) {
+    echo "Webhook ID: {$webhook->id}, URL: {$webhook->callbackUri}\n";
+}
+
+// Create new webhook
+$data = new WebhookSubscriptionRequestData('https://your-app.com/webhooks/alfa', ['transactions']);
+$baas->send(new CreateWebhookRequest($data));
+
+/**
+ * 2. Parsing incoming webhook payload (Webhook Controller logic)
+ */
+$rawPayload = [
+    [
+        'actionType' => 'create',
+        'eventTime' => '2023-10-27T10:00:00Z',
+        'object' => 'ul_transaction_default',
+        'data' => [
+            'transactionId' => 'TX-12345',
+            'amount' => ['amount' => 100.50, 'currencyName' => 'RUR'],
+            'direction' => 'CREDIT',
+            'paymentPurpose' => 'Test payment'
+        ]
+    ]
+];
+
+// Use the factory to parse the payload into a DTO
+$webhookDto = WebhookFactory::create($rawPayload);
+
+echo "Received Webhook: {$webhookDto->object} ({$webhookDto->actionType})\n";

examples/06_sbp_b2c_payout.php

@@ -0,0 +1,46 @@
+<?php
+
+require_once __DIR__ . '/../vendor/autoload.php';
+
+use Apoloz\AlfaBank\AlfaBank;
+use Apoloz\AlfaBank\Requests\B2C\CreateB2CPaymentRequest;
+use Apoloz\AlfaBank\Data\B2C\B2CPaymentRequestData;
+use Apoloz\AlfaBank\Data\B2C\B2CClientData;
+use Apoloz\AlfaBank\Data\B2C\B2CPaymentRecipientData;
+use Spatie\LaravelData\DataCollection;
+
+/**
+ * Example: B2C Payout via SBP (Phone Number).
+ */
+
+$baas = AlfaBank::baas(
+    certificatePath: 'path/to/cert.pem',
+    privateKeyPath: 'path/to/key.pem'
+);
+
+$payload = new B2CPaymentRequestData(
+    client: new B2CClientData(b2cClientId: 'your-uuid', partnerId: 123),
+    inn: '7700000000',
+    account: '40702810...',
+    total: 100.00,
+    signedBody: 'BASE64_SIGNATURE_HERE', // Signature of the payments data
+    payments: B2CPaymentRecipientData::collect([
+        [
+            'phone' => '79001112233',
+            'amount' => 100.00,
+            'nspkBankId' => '100000000001',
+            'sequence' => 'unique-payout-id-1'
+        ]
+    ], DataCollection::class)
+);
+
+$baas->login('client-id', 'client-secret');
+$response = $baas->send(new CreateB2CPaymentRequest($payload));
+
+if ($response->successful()) {
+    $data = $response->dto(); // B2CPaymentResponseData
+    echo "Payout request sent. Status: {$data->status}\n";
+} else {
+    echo "Error: " . $response->body() . "\n";
+}
+

examples/07_registry_signing.php

@@ -0,0 +1,65 @@
+<?php
+
+require_once __DIR__ . '/../vendor/autoload.php';
+
+use Apoloz\AlfaBank\AlfaBank;
+use Apoloz\AlfaBank\Utils\CmsSigner;
+use Apoloz\AlfaBank\Requests\Registries\CreateRegistryRequest;
+use Apoloz\AlfaBank\Data\Registries\RegistryRequestData;
+use Apoloz\AlfaBank\Data\Registries\RegistryPaymentData;
+use Apoloz\AlfaBank\Requests\Registries\SignRegistryRequest;
+use Apoloz\AlfaBank\Data\Registries\RegistrySignatureData;
+use Spatie\LaravelData\DataCollection;
+
+/**
+ * Example: Creating and Signing a Payment Registry (Batch Payments).
+ */
+
+$baas = AlfaBank::baas(
+    certificatePath: 'path/to/cert.pem',
+    privateKeyPath: 'path/to/key.pem'
+);
+
+// 1. Create Registry
+$payload = new RegistryRequestData(
+    payments: RegistryPaymentData::collect([
+        [
+            'amount' => 500.0,
+            'date' => date('Y-m-d'),
+            'payeeAccount' => '40702...',
+            'payeeBankBic' => '044...',
+            'payeeInn' => '770...',
+            'payeeName' => 'Vendor 1',
+            'payerAccount' => '40702...',
+            'purpose' => 'Payment for goods'
+        ]
+    ], DataCollection::class)
+);
+
+$baas->login('client-id', 'client-secret');
+$response = $baas->send(new CreateRegistryRequest($payload));
+$registryId = $response->dto()->id;
+
+echo "Registry Created: $registryId\n";
+
+// 2. Sign Registry
+// In real life, you might need to sign the digest provided by the bank 
+// or the registry content itself. This depends on the specific bank requirement.
+$signature = CmsSigner::sign(
+    $registryId, // Example data
+    file_get_contents('path/to/sign_cert.pem'),
+    file_get_contents('path/to/sign_key.pem')
+);
+
+$signatures = RegistrySignatureData::collect([
+    [
+        'base64Encoded' => $signature,
+        'signatureType' => 'RSA',
+        'certificateUuid' => 'YOUR_CERT_UUID'
+    ]
+], DataCollection::class);
+
+$baas->send(new SignRegistryRequest($registryId, $signatures));
+
+echo "Registry Signed.\n";
+