Bayrewards Laravel Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require palpalani/bayrewards-laravel
   

   Publish the config file:

   php artisan vendor:publish --provider="Palpalani\BayRewards\BayRewardsServiceProvider" --tag="config"
   

2. Configuration: Update .env with your BayRewards credentials:

   BAYREWARDS_API_KEY=your_api_key_here
   BAYREWARDS_API_SECRET=your_api_secret_here
   BAYREWARDS_ENVIRONMENT=sandbox # or 'live'
   

3. First Use Case: Trigger a reward redemption in a controller:

   use Palpalani\BayRewards\Facades\BayRewards;
   
   public function redeemReward(Request $request)
   {
       $response = BayRewards::redeem($request->input('reward_id'), $request->input('customer_id'));
       return response()->json($response);
   }
   

Key Starting Points

• Facade: Use BayRewards facade for quick access to all methods.
• Config: Check config/bayrewards.php for available endpoints and default settings.
• Documentation: Review the BayRewards API docs for payload structures.

Implementation Patterns

Core Workflows

1. Reward Redemption:

   // Basic redemption
   $result = BayRewards::redeem($rewardId, $customerId);
   
   // With custom payload
   $payload = [
       'reward_id' => $rewardId,
       'customer_id' => $customerId,
       'metadata' => ['order_id' => 12345]
   ];
   $result = BayRewards::redeem($payload);
   

2. Customer Rewards Balance:

   $balance = BayRewards::getCustomerBalance($customerId);
   

3. Event-Based Integration: Listen to bayrewards.reward.redeemed events for post-redemption logic:

   BayRewards::redeem($rewardId, $customerId)
       ->then(function ($response) {
           // Post-redemption logic (e.g., update user profile)
       });
   

Integration Tips

• Middleware: Use middleware to validate API keys or enforce rate limits:

  public function handle(Request $request, Closure $next)
  {
      if (!BayRewards::isApiKeyValid()) {
          abort(403, 'Invalid API key');
      }
      return $next($request);
  }
  

• Queue Jobs: Offload reward processing to queues for async handling:

  BayRewards::dispatchRedeemJob($rewardId, $customerId);
  

• Webhooks: Set up webhook endpoints in routes/web.php:

  Route::post('/bayrewards/webhook', [BayRewardsWebhookController::class, 'handle']);
  

• Testing: Use the sandbox environment for local testing:

  BayRewards::setEnvironment('sandbox');
  

Gotchas and Tips

Common Pitfalls

1. API Key/Secret Mismatch:

   • Ensure .env values match the BayRewards dashboard.
   • Debug with:

     BayRewards::getLastError(); // Check for auth failures
     

2. Rate Limiting:

   • BayRewards enforces rate limits (e.g., 60 requests/minute).
   • Implement exponential backoff in retries:

     BayRewards::withRetry(3, 1000)->redeem($rewardId, $customerId);
     

3. Payload Validation:

   • Always validate required fields (reward_id, customer_id) before calling SDK methods.
   • Use Laravel’s ValidatesRequests trait for consistency.

4. Webhook Verification:

   • Verify webhook signatures to avoid spoofing:

     if (!BayRewards::verifyWebhookSignature($request->header('X-Signature'), $request->getContent())) {
         abort(403);
     }
     

Debugging Tips

• Enable Logging:

  BayRewards::enableLogging(); // Logs to storage/logs/bayrewards.log
  

• Mock Responses (for testing):

  BayRewards::mockResponse('redeem', ['success' => true]);
  

Extension Points

1. Custom Responses: Override default responses by binding a custom handler:

   BayRewards::bindResponseHandler(function ($response, $method) {
       return ['custom' => 'data'];
   });
   

2. Event Extensions: Extend events to trigger custom logic:

   event(new \Palpalani\BayRewards\Events\RewardRedeemed($rewardId, $customerId));
   

3. API Endpoint Overrides: Configure custom endpoints in config/bayrewards.php:

   'endpoints' => [
       'redeem' => 'https://custom-api.bayrewards.com/redeem',
   ],
   

Configuration Quirks

• Environment-Specific Settings: Use config/bayrewards.php to define environment-specific keys:

  'environments' => [
      'sandbox' => [
          'api_key' => env('BAYREWARDS_SANDBOX_KEY'),
          'api_secret' => env('BAYREWARDS_SANDBOX_SECRET'),
      ],
      'live' => [
          'api_key' => env('BAYREWARDS_LIVE_KEY'),
          'api_secret' => env('BAYREWARDS_LIVE_SECRET'),
      ],
  ],
  

• Timeout Handling: Default timeout is 30 seconds. Adjust in config:

  'timeout' => 60, // seconds