Add category level attributes api support

README.md

@@ -37,7 +37,8 @@ facade
 │  └─ new                  - Obtain new session token
 ├─ category/           - Category endpoint
 │  ├─ get                  - Get product listing category
-│  └─ getAttributes        - Get system-defined attributes based on category ID
+│  ├─ getAttributes        - Get system-defined attributes based on category ID
+│  └─ getLevelAttribute    - Get next-level attribute based on category, attribute and value ID (e.g. car_model values)
 └─ product/            - Product endpoint
    └─ getGroup             - Get product group
 ```

src/Endpoint/CategoryEndpoint.php

@@ -8,6 +8,8 @@
 use Kyto\Alibaba\Factory\CategoryFactory;
 use Kyto\Alibaba\Model\Category;
 use Kyto\Alibaba\Model\CategoryAttribute;
+use Kyto\Alibaba\Model\CategoryLevelAttribute;
+use Kyto\Alibaba\Model\CategoryLevelAttributeRequest;
 
 class CategoryEndpoint
 {
@@ -68,4 +70,29 @@ public function getAttributes(string $categoryId): array
 
         return $result;
     }
+
+    /**
+     * Get next-level attribute based on category, attribute and optionally level attribute value ID.
+     * @link https://developer.alibaba.com/en/doc.htm?spm=a2728.12183079.k2mwm9fd.1.4b3630901WuQWY#?docType=2&docId=48659
+     *
+     * @param ?string $valueId provide null to fetch first level
+     */
+    public function getLevelAttribute(
+        string $categoryId,
+        string $attributeId,
+        ?string $valueId = null
+    ): CategoryLevelAttribute {
+        $attributeValueRequest = new CategoryLevelAttributeRequest();
+        $attributeValueRequest->categoryId = $categoryId;
+        $attributeValueRequest->attributeId = $attributeId;
+        $attributeValueRequest->valueId = $valueId ?? '0';
+
+        $data = $this->client->request([
+            'method' => 'alibaba.icbu.category.level.attr.get',
+            'attribute_value_request' => json_encode($attributeValueRequest)
+        ]);
+
+        $attribute = $data['alibaba_icbu_category_level_attr_get_response']['result_list'];
+        return $this->categoryFactory->createLevelAttribute($attribute);
+    }
 }

src/Exception/AlibabaException.php

@@ -12,20 +12,20 @@ class AlibabaException extends \RuntimeException
     public function __construct(
         string $message,
         int $code,
-        private string $subMessage,
-        private string $subCode,
+        private ?string $subMessage,
+        private ?string $subCode,
         ?\Throwable $previous = null
     ) {
         $message = sprintf('%s. Sub-code: "%s". Sub-message: "%s".', $message, $this->subCode, $this->subMessage);
         parent::__construct($message, $code, $previous);
     }
 
-    public function getSubMessage(): string
+    public function getSubMessage(): ?string
     {
         return $this->subMessage;
     }
 
-    public function getSubCode(): string
+    public function getSubCode(): ?string
     {
         return $this->subCode;
     }

src/Factory/CategoryFactory.php

@@ -4,6 +4,8 @@
 
 namespace Kyto\Alibaba\Factory;
 
+use Kyto\Alibaba\Model\CategoryLevelAttribute;
+use Kyto\Alibaba\Model\CategoryLevelAttributeValue;
 use Kyto\Alibaba\Util\Formatter;
 use Kyto\Alibaba\Model\Category;
 use Kyto\Alibaba\Model\CategoryAttribute;
@@ -15,7 +17,7 @@
 class CategoryFactory
 {
     /**
-     * @param mixed[] $data
+     * @param array<string, mixed> $data
      */
     public function createCategory(array $data): Category
     {
@@ -34,7 +36,7 @@ public function createCategory(array $data): Category
     }
 
     /**
-     * @param mixed[] $data
+     * @param array<string, mixed> $data
      */
     public function createAttribute(array $data): CategoryAttribute
     {
@@ -64,7 +66,7 @@ public function createAttribute(array $data): CategoryAttribute
     }
 
     /**
-     * @param mixed[] $data
+     * @param array<string, mixed> $data
      */
     public function createAttributeValue(array $data): CategoryAttributeValue
     {
@@ -77,4 +79,36 @@ public function createAttributeValue(array $data): CategoryAttributeValue
 
         return $model;
     }
+
+    /**
+     * @param array<string, mixed> $data
+     */
+    public function createLevelAttribute(array $data): CategoryLevelAttribute
+    {
+        $model = new CategoryLevelAttribute();
+
+        $model->id = (string) $data['property_id'];
+        $model->name = (string) $data['property_en_name'];
+
+        $model->values = [];
+        $decodedValues = json_decode($data['values'], true);
+        foreach ($decodedValues as $value) {
+            $model->values[] = $this->createLevelAttributeValue($value);
+        }
+
+        return $model;
+    }
+
+    /**
+     * @param array<string, mixed> $data
+     */
+    public function createLevelAttributeValue(array $data): CategoryLevelAttributeValue
+    {
+        $model = new CategoryLevelAttributeValue();
+        $model->name = (string) $data['name'];
+        $model->id = (string) $data['id'];
+        $model->isLeaf = isset($data['leaf']);
+
+        return $model;
+    }
 }

src/Model/CategoryAttribute.php

@@ -12,7 +12,9 @@ class CategoryAttribute
 
     // TODO: change to enums once all values would be known
     public string $inputType; // Known values: single_select, multi_select, input
-    public string $showType; // Known values: list_box (single_select), check_box (multi_select), input (input)
+
+    // Known values: list_box (single_select), check_box (multi_select), input (input), group_table (single_select)
+    public string $showType;
     public string $valueType; // Known values: string, number
 
     public bool $isSku;

src/Model/CategoryLevelAttribute.php

@@ -0,0 +1,14 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Kyto\Alibaba\Model;
+
+class CategoryLevelAttribute
+{
+    public string $id;
+    public string $name;
+
+    /** @var CategoryLevelAttributeValue[] */
+    public array $values;
+}

src/Model/CategoryLevelAttributeRequest.php

@@ -0,0 +1,27 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Kyto\Alibaba\Model;
+
+/**
+ * The actual request needs it as a json, so use json_encode() on this model before you use it in a request.
+ */
+class CategoryLevelAttributeRequest implements \JsonSerializable
+{
+    public string $categoryId;
+    public string $attributeId;
+    public string $valueId;
+
+    /**
+     * @return array<string, string>
+     */
+    public function jsonSerialize(): array
+    {
+        return [
+            'cat_id' => $this->categoryId,
+            'attr_id' => $this->attributeId,
+            'value_id' => $this->valueId
+        ];
+    }
+}

src/Model/CategoryLevelAttributeValue.php

@@ -0,0 +1,12 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Kyto\Alibaba\Model;
+
+class CategoryLevelAttributeValue
+{
+    public string $id;
+    public string $name;
+    public bool $isLeaf;
+}

tests/Endpoint/CategoryEndpointTest.php

@@ -9,6 +9,8 @@
 use Kyto\Alibaba\Factory\CategoryFactory;
 use Kyto\Alibaba\Model\Category;
 use Kyto\Alibaba\Model\CategoryAttribute;
+use Kyto\Alibaba\Model\CategoryLevelAttribute;
+use Kyto\Alibaba\Model\CategoryLevelAttributeRequest;
 use PHPUnit\Framework\MockObject\MockObject;
 use PHPUnit\Framework\TestCase;
 
@@ -98,4 +100,30 @@ public function testGetAttributes(): void
         $actual = $this->categoryEndpoint->getAttributes($id);
         self::assertSame($result, $actual);
     }
+
+    public function testGetLevelAttributes(): void
+    {
+        $attributeValueRequestBody = '{"cat_id":"1","attr_id":"1","value_id":"0"}';
+        $levelAttribute = ['LevelAttribute'];
+        $data = ['alibaba_icbu_category_level_attr_get_response' => ['result_list' => $levelAttribute]];
+
+        $this->client
+            ->expects(self::once())
+            ->method('request')
+            ->with([
+                'method' => 'alibaba.icbu.category.level.attr.get',
+                'attribute_value_request' => $attributeValueRequestBody,
+            ])
+            ->willReturn($data);
+
+        $result = new CategoryLevelAttribute();
+
+        $this->categoryFactory
+            ->expects(self::once())
+            ->method('createLevelAttribute')
+            ->willReturn($result);
+
+        $actual = $this->categoryEndpoint->getLevelAttribute('1', '1', null);
+        self::assertSame($result, $actual);
+    }
 }