feat(catalog): expose product unavailability messages

app/Domains/Catalog/Services/CatalogItemAllowanceService.php

@@ -8,6 +8,10 @@ use Illuminate\Support\Collection;
 
 class CatalogItemAllowanceService
 {
+    private const USER_QUOTA_REACHED_MESSAGE = 'Alcanzaste el cupo máximo permitido para este producto.';
+
+    private const OUT_OF_STOCK_MESSAGE = 'Este producto no tiene stock disponible.';
+
     public function __construct(
         private readonly UserPurchaseLimitService $purchaseLimits,
     ) {}
@@ -37,4 +41,17 @@ class CatalogItemAllowanceService
 
         return min($availableStock, $remainingUserQuota);
     }
+
+    public function unavailableMessage(?int $availableStock, ?int $remainingUserQuota): ?string
+    {
+        if ($remainingUserQuota !== null && $remainingUserQuota <= 0) {
+            return self::USER_QUOTA_REACHED_MESSAGE;
+        }
+
+        if ($availableStock !== null && $availableStock <= 0) {
+            return self::OUT_OF_STOCK_MESSAGE;
+        }
+
+        return null;
+    }
 }