My Theresa Api Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require atm/my_theresa_api
   

   Publish the configuration file:

   php artisan vendor:publish --provider="Atm\MyTheresaApi\MyTheresaApiServiceProvider" --tag="config"
   

2. First Use Case: Fetching Product Data Initialize the client in config/my_theresa_api.php:

   'client' => [
       'client_id' => env('MY_THERESA_CLIENT_ID'),
       'client_secret' => env('MY_THERESA_CLIENT_SECRET'),
       'api_url' => env('MY_THERESA_API_URL', 'https://api.mytheresa.com'),
   ],
   

   Use the facade in a controller or service:

   use Atm\MyTheresaApi\Facades\MyTheresaApi;
   
   $products = MyTheresaApi::get('/products', [
       'filter' => ['category' => 'women'],
       'limit' => 10
   ]);
   

3. Key Files to Review

   • src/Facades/MyTheresaApi.php (Facade entry point)
   • src/Client.php (Core HTTP client logic)
   • src/Exceptions/ (Custom exceptions for error handling)

Implementation Patterns

Common Workflows

1. Authentication & Token Management

• Use the facade to refresh tokens automatically:

  MyTheresaApi::setToken($refreshToken); // Manually set if needed
  $response = MyTheresaApi::get('/protected/endpoint'); // Auto-handles token refresh
  

• Listen for token refresh events:

  MyTheresaApi::onTokenRefreshed(function ($newToken) {
      Log::debug("Token refreshed. New token: " . substr($newToken, 0, 10) . "...");
  });
  

2. Pagination & Rate Limiting

• Handle paginated responses:

  $paginator = MyTheresaApi::getPaginated('/products', [
      'limit' => 50,
      'page' => 1
  ]);
  foreach ($paginator as $product) {
      // Process each product
  }
  

• Implement retry logic for rate-limited requests:

  MyTheresaApi::withRetry(3, 1000)->get('/products'); // Retry 3 times with 1s delay
  

3. Data Transformation

• Use the built-in mapper for standard responses:

  $product = MyTheresaApi::get('/products/123')->mapToProduct();
  

• Extend the mapper for custom fields:

  MyTheresaApi::extendMapper('product', function ($data) {
      return (object) array_merge($data, [
          'formatted_price' => '$' . number_format($data->price / 100, 2)
      ]);
  });
  

4. Webhook Handling

• Register a webhook listener:

  MyTheresaApi::listenForWebhooks('inventory_update', function ($payload) {
      // Handle inventory updates
  });
  

• Verify webhook signatures:

  $isValid = MyTheresaApi::verifyWebhookSignature(
      $request->getContent(),
      $request->header('X-Signature')
  );
  

Integration Tips

Laravel Ecosystem

• Queue Jobs for API Calls

  MyTheresaApi::dispatchSync('/products')->onQueue('mytheresa');
  

• Cache Responses

  $products = Cache::remember('mytheresa_products', now()->addHours(1), function () {
      return MyTheresaApi::get('/products');
  });
  

• Use with Scout for Search

  class MyTheresaScoutEngine extends ScoutEngine {
      public function search($query) {
          return MyTheresaApi::search($query);
      }
  }
  

Testing

• Mock the API client in tests:

  MyTheresaApi::shouldReceive('get')
      ->once()
      ->with('/products/123')
      ->andReturn((object) ['id' => 123, 'name' => 'Test Product']);
  

Gotchas and Tips

Pitfalls

1. Token Expiry Handling

   • The package auto-refreshes tokens, but ensure your .env has:

     MY_THERESA_TOKEN_REFRESH_URL=https://api.mytheresa.com/oauth/token
     

   • Debug Tip: Enable debug mode in config:

     'debug' => env('APP_DEBUG', false),
     

     to log token refreshes.

2. Rate Limiting

   • MyTheresa enforces rate limits (e.g., 100 requests/minute). Use:

     MyTheresaApi::withRateLimit(100, 60)->get('/products');
     

   • Gotcha: The package doesn’t auto-throttle; implement exponential backoff in your app if needed.

3. Data Format Inconsistencies

   • Some endpoints return snake_case while others use camelCase. Normalize with:

     MyTheresaApi::setNormalizeKeys(true); // Converts all keys to snake_case
     

4. Webhook Idempotency

   • MyTheresa webhooks may retry failed deliveries. Use a webhook_signature table to track processed payloads:

     MyTheresaApi::markWebhookAsProcessed($payload['id'], $signature);
     

Debugging

• Enable Verbose Logging

  MyTheresaApi::setLogLevel(Log::DEBUG);
  

• Inspect Raw Responses

  $response = MyTheresaApi::get('/products', [], true); // Returns raw response
  

• Common HTTP Errors

  Error Code	Cause	Solution
  401	Invalid token	Refresh token or check credentials
  429	Rate limit exceeded	Implement retry logic
  500	Server error	Check MyTheresa status or contact support

Extension Points

1. Custom Endpoints Add a new endpoint class:

   namespace Atm\MyTheresaApi\Endpoints;
   
   class CustomEndpoint extends Endpoint {
       protected $path = '/custom/path';
       protected $methods = ['GET', 'POST'];
   }
   

   Register it in config/my_theresa_api.php:

   'endpoints' => [
       'custom' => \Atm\MyTheresaApi\Endpoints\CustomEndpoint::class,
   ],
   

2. Middleware Attach middleware to all requests:

   MyTheresaApi::addMiddleware(function ($request) {
       $request->headers->set('X-Custom-Header', 'value');
   });
   

3. Event Listeners Extend the event system:

   MyTheresaApi::listen('before_request', function ($request) {
       // Modify request before sending
   });