Bsap Account Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require besmartand-pro/bsap-account-bundle
   

   Register the bundle in config/app.php under providers:

   BesmartandPro\BsapAccountBundle\BsapAccountBundle::class,
   

2. Publish Configuration

   php artisan vendor:publish --provider="BesmartandPro\BsapAccountBundle\BsapAccountServiceProvider" --tag="config"
   

   Edit config/bsap-account.php to set your API credentials and endpoints.

3. First Use Case: Fetching an Account Inject the service into a controller or command:

   use BesmartandPro\BsapAccountBundle\Service\BsapAccountService;
   
   public function __construct(private BsapAccountService $accountService) {}
   
   public function showAccount($accountId) {
       $account = $this->accountService->getAccount($accountId);
       return response()->json($account);
   }
   

Key Configuration

• API Credentials: Set client_id, client_secret, and token_endpoint in the config.
• Base URL: Configure api_base_url for the Bsap API.

Implementation Patterns

Common Workflows

1. Account Management

   • Fetching Accounts:

     $accounts = $this->accountService->listAccounts(['limit' => 10]);
     

   • Creating/Updating:

     $newAccount = $this->accountService->createAccount([
         'name' => 'Test Account',
         'currency' => 'EUR'
     ]);
     

2. Transactions

   • List Transactions:

     $transactions = $this->accountService->getTransactions($accountId, [
         'from' => '2024-01-01',
         'to' => '2024-12-31'
     ]);
     

   • Initiate Transfer:

     $transfer = $this->accountService->transfer([
         'from_account_id' => $sourceId,
         'to_account_id' => $targetId,
         'amount' => 100.50,
         'currency' => 'EUR'
     ]);
     

3. Webhooks

   • Subscribe to events in config/bsap-account.php:

     'webhooks' => [
         'enabled' => true,
         'events' => ['account.created', 'transaction.processed'],
         'secret' => env('BSAP_WEBHOOK_SECRET')
     ],
     

   • Handle incoming webhooks via the BsapWebhookController (published with php artisan vendor:publish --tag="webhook").

Integration Tips

• Rate Limiting: The bundle includes middleware for API rate limits. Customize BsapRateLimitMiddleware in app/Http/Kernel.php if needed.
• Caching: Enable caching for account/transaction data by setting 'cache_enabled' => true in config and implementing BsapAccountCacheInterface.
• Logging: Use the BsapLogger facade to log API interactions:

  \BsapAccountBundle\Facades\BsapLogger::info('Account fetched', ['account_id' => $accountId]);
  

Gotchas and Tips

Pitfalls

1. Authentication Failures

   • Ensure client_id and client_secret are correct and the token endpoint is reachable.
   • Debug with:

     $this->accountService->getAccessToken(); // Check if token is valid
     

2. Webhook Verification

   • Always verify webhook payloads using the BsapWebhookVerifier:

     $verifier = new \BesmartandPro\BsapAccountBundle\Service\BsapWebhookVerifier($request);
     if (!$verifier->isValid()) {
         abort(403, 'Invalid webhook signature');
     }
     

3. Deprecated Endpoints

   • The bundle may not support all Bsap API versions. Check the changelog for breaking changes.

Debugging

• Enable Debug Mode:

  'debug' => env('BSAP_DEBUG', false), // Logs raw API responses
  

• Mock API Calls: Use the BsapAccountService with a mock client:

  $this->app->bind(BsapAccountService::class, function ($app) {
      return new BsapAccountService(new \GuzzleHttp\Client(), new \BesmartandPro\BsapAccountBundle\Service\MockBsapClient());
  });
  

Extension Points

1. Custom Responses Override the default response format by extending BsapAccountService and injecting a custom BsapResponseFormatter:

   class CustomBsapAccountService extends BsapAccountService {
       public function __construct(BsapClient $client, BsapResponseFormatter $formatter) {
           parent::__construct($client, $formatter);
       }
   }
   

2. Additional API Methods Extend the BsapClient to support unsupported endpoints:

   $client->addCustomMethod('get', '/custom-endpoint', function ($params) {
       return $this->request('GET', '/custom-endpoint', $params);
   });
   

3. Event Listeners Subscribe to Bsap events (e.g., BsapAccountCreated) in EventServiceProvider:

   protected $listen = [
       \BesmartandPro\BsapAccountBundle\Events\BsapAccountCreated::class => [
           \App\Listeners\LogAccountCreation::class,
       ],
   ];
   

Config Quirks

• Environment Variables: Prefix all config keys with BSAP_ (e.g., BSAP_API_BASE_URL).
• Default Values: The bundle uses null for optional fields. Explicitly set null in your requests to override defaults.