Ss Laravel Package

Getting Started

Minimal Setup

1. Installation Add the package via Composer:

   composer require milestone/ss
   

   Publish the configuration file:

   php artisan vendor:publish --provider="Milestone\SS\SSServiceProvider"
   

2. Configuration Locate the published config file at config/ss.php and update API credentials (e.g., api_key, base_url) with your ePlus Smart Sale credentials.

3. First Use Case: Fetching a Product Use the facade to fetch a product by ID:

   use Milestone\SS\Facades\SS;
   
   $product = SS::product()->get(123);
   

   Ensure the SSServiceProvider is registered in config/app.php under providers.

Implementation Patterns

Core Workflows

1. Product Management

   • Fetching Products:

     $products = SS::product()->all(); // All products
     $product = SS::product()->get(456); // Single product
     

   • Filtering Products: Use query parameters (e.g., category_id, price_range):

     $filtered = SS::product()->get(['category_id' => 10, 'min_price' => 50]);
     

2. Order Processing

   • Creating Orders:

     $order = SS::order()->create([
         'customer_id' => 789,
         'items' => [
             ['product_id' => 123, 'quantity' => 2],
             ['product_id'  => 456, 'quantity' => 1],
         ],
     ]);
     

   • Fetching Orders:

     $orders = SS::order()->all(['customer_id' => 789]);
     

3. Promotion Handling

   • Applying Promotions:

     $promotion = SS::promotion()->apply(10, ['product_id' => 123]); // 10% discount
     

Integration Tips

• API Rate Limiting: Monitor API calls to avoid hitting rate limits. Cache responses where possible:

  $cachedProduct = Cache::remember("product_{$id}", now()->addHours(1), function() use ($id) {
      return SS::product()->get($id);
  });
  

• Error Handling: Wrap API calls in try-catch blocks to handle HTTP errors gracefully:

  try {
      $product = SS::product()->get(123);
  } catch (\Milestone\SS\Exceptions\SSException $e) {
      Log::error("SS API Error: " . $e->getMessage());
      return response()->json(['error' => 'Failed to fetch product'], 500);
  }
  

• Webhook Listeners: Set up Laravel events for order status updates (if the package supports webhooks). Example:

  SS::order()->onStatusUpdate(function ($order) {
      // Trigger email/SMS notifications
  });
  

Gotchas and Tips

Pitfalls

1. Deprecated API Endpoints The package was last updated in 2020, so ensure the API endpoints (config/ss.php) match the current ePlus Smart Sale API schema. Test endpoints manually if unsure.

2. Authentication Issues

   • Verify api_key and base_url in config/ss.php are correct.
   • If using OAuth, ensure the token is refreshed periodically (the package may not handle this automatically).

3. Data Mismatches The package may return raw API responses. Sanitize data before use:

   $product = SS::product()->get(123);
   $formattedPrice = number_format($product->price / 100, 2); // Assuming price is in cents
   

4. Lack of Documentation Since the package has 0 stars and no dependents, assume minimal documentation. Use dd() or var_dump() to inspect raw responses:

   $response = SS::product()->get(123);
   dd($response); // Inspect structure
   

Debugging Tips

• Enable Debug Mode: Set 'debug' => true in config/ss.php to log API requests/responses to storage/logs/ss.log.
• HTTP Client Inspection: Extend the package’s HTTP client to add debug headers:

  // In a service provider or boot method
  SS::extend(function ($client) {
      $client->getClient()->getEmitter()->attach(
          new \GuzzleHttp\Middleware::tap(function ($request) {
              \Log::debug("SS Request: " . $request->getUri());
          })
      );
  });
  

Extension Points

1. Custom API Endpoints Override the base URL or endpoints dynamically:

   SS::setBaseUrl('https://custom-api.eplus.com');
   SS::product()->setEndpoint('v2/products');
   

2. Response Transformers Extend the package to transform raw API responses:

   SS::extend(function ($client) {
       $client->getTransformer()->register('product', function ($data) {
           return (object) [
               'id' => $data->id,
               'name' => $data->name,
               'formatted_price' => '$' . ($data->price / 100),
           ];
       });
   });
   

3. Event Listeners Listen for package events (if supported) to hook into order/product updates:

   // In EventServiceProvider
   public function boot()
   {
       SS::order()->onCreated(function ($order) {
           // Send analytics or update inventory
       });
   }
   

4. Fallback Mechanisms Implement retries for failed requests using Laravel’s retry helper or a package like spatie/laravel-retryable:

   use Illuminate\Support\Facades\Retry;
   
   Retry::retry(3, function () {
       $product = SS::product()->get(123);
   }, function ($e) {
       \Log::warning("Retrying SS API call: " . $e->getMessage());
   });