feat(catalog): expose availability policies

app/Domains/Catalog/Services/CatalogItemAllowanceService.php

@@ -42,16 +42,75 @@ class CatalogItemAllowanceService
         return min($availableStock, $remainingUserQuota);
     }
 
-    public function unavailableMessage(?int $availableStock, ?int $remainingUserQuota): ?string
-    {
+    /**
+     * @return array{
+     *     maximum_quantity: int|null,
+     *     restrictions: list<array{code: string, message: string, scope: string}>,
+     *     capabilities: array{select_variant: bool, change_quantity: bool, add_to_cart: bool, buy_now: bool}
+     * }
+     */
+    public function availability(
+        ?int $availableStock,
+        ?int $remainingUserQuota,
+        string $scope = 'product',
+    ): array {
+        $restrictions = [];
+
         if ($remainingUserQuota !== null && $remainingUserQuota <= 0) {
-            return self::USER_QUOTA_REACHED_MESSAGE;
+            $restrictions[] = [
+                'code' => 'user_quota_reached',
+                'message' => self::USER_QUOTA_REACHED_MESSAGE,
+                'scope' => $scope,
+            ];
         }
 
         if ($availableStock !== null && $availableStock <= 0) {
-            return self::OUT_OF_STOCK_MESSAGE;
+            $restrictions[] = [
+                'code' => 'out_of_stock',
+                'message' => self::OUT_OF_STOCK_MESSAGE,
+                'scope' => $scope,
+            ];
         }
 
-        return null;
+        $capabilities = [
+            'select_variant' => true,
+            'change_quantity' => true,
+            'add_to_cart' => true,
+            'buy_now' => true,
+        ];
+
+        foreach ($restrictions as $restriction) {
+            /** @var array<string, bool> $policy */
+            $policy = config("catalog.availability_policies.{$restriction['code']}", []);
+
+            foreach ($capabilities as $capability => $allowed) {
+                $capabilities[$capability] = $allowed && ($policy[$capability] ?? true);
+            }
+        }
+
+        return [
+            'maximum_quantity' => $this->maximumAddableQuantity(
+                $availableStock,
+                $remainingUserQuota,
+            ),
+            'restrictions' => $restrictions,
+            'capabilities' => $capabilities,
+        ];
+    }
+
+    /** @return array<string, mixed> */
+    public function purchaseLimitExceededAvailability(int $maximumQuantity, string $message): array
+    {
+        $availability = $this->availability(null, $maximumQuantity);
+
+        if ($maximumQuantity > 0) {
+            $availability['restrictions'][] = [
+                'code' => 'requested_quantity_exceeds_user_quota',
+                'message' => $message,
+                'scope' => 'product',
+            ];
+        }
+
+        return $availability;
     }
 }