releases/2026.05

README.md

@@ -236,7 +236,7 @@ The SDK includes comprehensive validation and error handling. For testing:
 
 1. Use the validation methods to check data before syncing.
 2. Start with small batches to verify configuration
-3. Monitor API responses for any issues
+3. Monitor API responses for any issues.
 
 ## License
 

src/Adapters/PrestaShopAdapter.php

@@ -58,7 +58,7 @@ private function transformProduct(array $product): array
     {
         $result = [
             'id' => $this->getRequiredField($product, 'remoteId'),
-            'sku' => $this->getRequiredField($product, 'sku'),
+            'sku' => (string) ($product['sku'] ?? ''),
             'price' => $this->getRequiredField($product, 'price'),
             'basePrice' => $this->getRequiredField($product, 'basePrice'),
             'priceTaxExcluded' => $this->getRequiredField($product, 'priceTaxExcluded'),

src/Adapters/PrestaShopAdapterV2.php

@@ -17,6 +17,20 @@
  */
 class PrestaShopAdapterV2
 {
+    public const CUSTOM_FIELD_PREFIX = 'custom_';
+
+    private const CUSTOM_FIELD_TYPE_TEXT = 'text';
+
+    private const CUSTOM_FIELD_NAME_PATTERN = '/^[a-zA-Z0-9_]{1,64}$/D';
+
+    private const CUSTOM_FIELD_TYPE_DATE = 'date';
+
+    private const MYSQL_ZERO_DATE_PREFIX = '0000-00-00';
+
+    private const LITERAL_ANGLE_PATTERN = '/<(?![a-zA-Z\/!?][^<>]*>)/';
+
+    private const LITERAL_ANGLE_SENTINEL = "\x01";
+
     /**
      * @var array<int, array{type: string, product_index: int, product_id: string, message: string, exception: string}>
      */
@@ -81,7 +95,7 @@ public function transform(array $prestaShopData): array
     public function transformProduct(array $product): Product
     {
         $id = $this->getRequiredField($product, 'remoteId');
-        $sku = $this->getRequiredField($product, 'sku');
+        $sku = (string) ($product['sku'] ?? '');
 
         $pricing = new ProductPricing(
             $this->extractPrice($product, 'price'),
@@ -145,6 +159,8 @@ public function transformProduct(array $product): Product
         // Handle features
         $this->transformFeatures($additionalFields, (array) ($product['features'] ?? []));
 
+        $this->transformCustomFields($additionalFields, (array) ($product['customFields'] ?? []));
+
         // Handle tags
         $this->transformTags($additionalFields, $product['tags'] ?? []);
 
@@ -180,9 +196,6 @@ public function transformVariant(array $variant, string $locale): ProductVariant
         }
 
         $sku = (string) ($variant['sku'] ?? '');
-        if ($sku === '') {
-            throw new ValidationException("Variant 'sku' is required");
-        }
 
         $pricing = new ProductPricing(
             $this->extractPrice($variant, 'price'),
@@ -588,6 +601,72 @@ private function transformFeatures(array &$result, array $features): void
         }
     }
 
+    /**
+     * Entry shape: array{name: string, type: 'text'|'integer'|'double'|'boolean'|'date', value?: mixed, localizedValues?: array<string, mixed>}
+     *
+     * @param array<string, mixed> $result
+     * @param array<int, mixed> $customFields
+     */
+    private function transformCustomFields(array &$result, array $customFields): void
+    {
+        foreach ($customFields as $field) {
+            if (!is_array($field)) {
+                continue;
+            }
+
+            $name = isset($field['name']) && is_string($field['name']) ? $field['name'] : '';
+            if (preg_match(self::CUSTOM_FIELD_NAME_PATTERN, $name) !== 1) {
+                continue;
+            }
+
+            $type = isset($field['type']) && is_string($field['type']) ? $field['type'] : self::CUSTOM_FIELD_TYPE_TEXT;
+            $fieldName = self::CUSTOM_FIELD_PREFIX . $name;
+
+            if (isset($field['localizedValues']) && is_array($field['localizedValues'])) {
+                $this->addLocalizedField($result, $fieldName, $field['localizedValues'], $type);
+
+                continue;
+            }
+
+            if (!isset($field['value'])) {
+                continue;
+            }
+
+            $stringValue = $this->stringifyFieldValue($field['value']);
+
+            if ($stringValue === null) {
+                continue;
+            }
+
+            $cleanValue = $this->cleanCustomFieldValue($stringValue, $type);
+
+            if ($cleanValue === null) {
+                continue;
+            }
+
+            $result[$fieldName] = $cleanValue;
+        }
+    }
+
+    /**
+     * @return string|null
+     */
+    private function cleanCustomFieldValue(string $value, string $type): ?string
+    {
+        $cleanValue = $type === self::CUSTOM_FIELD_TYPE_TEXT ? $this->stripHtmlTags($value) : $value;
+        $cleanValue = trim($cleanValue);
+
+        if ($cleanValue === '') {
+            return null;
+        }
+
+        if ($type === self::CUSTOM_FIELD_TYPE_DATE && str_starts_with($cleanValue, self::MYSQL_ZERO_DATE_PREFIX)) {
+            return null;
+        }
+
+        return $cleanValue;
+    }
+
     /**
      * Transform tags to create localized fields.
      *
@@ -623,28 +702,67 @@ private function transformTags(array &$result, mixed $tags): void
      *
      * @param array<string, mixed> $result
      * @param string $fieldName
-     * @param array<string, string> $localizedValues
+     * @param array<array-key, mixed> $localizedValues
+     * @param string|null $customFieldType
      */
-    private function addLocalizedField(array &$result, string $fieldName, array $localizedValues): void
-    {
+    private function addLocalizedField(
+        array &$result,
+        string $fieldName,
+        array $localizedValues,
+        ?string $customFieldType = null
+    ): void {
         if (empty($localizedValues)) {
             return;
         }
 
         foreach ($localizedValues as $locale => $value) {
-            if (
-                !is_string($locale) || $locale === '' ||
-                $value === null || $value === ''
-            ) {
+            if (!is_string($locale) || $locale === '' || $value === '') {
                 continue;
             }
 
-            $cleanValue = strip_tags((string) $value);
+            $stringValue = $this->stringifyFieldValue($value);
+
+            if ($stringValue === null) {
+                continue;
+            }
+
+            if ($customFieldType === null) {
+                $result["{$fieldName}_{$locale}"] = strip_tags($stringValue);
+
+                continue;
+            }
+
+            $cleanValue = $this->cleanCustomFieldValue($stringValue, $customFieldType);
+
+            if ($cleanValue === null) {
+                continue;
+            }
 
             $result["{$fieldName}_{$locale}"] = $cleanValue;
         }
     }
 
+    private function stripHtmlTags(string $value): string
+    {
+        $guarded = str_replace(self::LITERAL_ANGLE_SENTINEL, '', $value);
+        $guarded = preg_replace(self::LITERAL_ANGLE_PATTERN, self::LITERAL_ANGLE_SENTINEL, $guarded) ?? $guarded;
+
+        return str_replace(self::LITERAL_ANGLE_SENTINEL, '<', strip_tags($guarded));
+    }
+
+    private function stringifyFieldValue(mixed $value): ?string
+    {
+        if (is_bool($value)) {
+            return $value ? 'true' : 'false';
+        }
+
+        if (is_scalar($value) || $value instanceof \Stringable) {
+            return (string) $value;
+        }
+
+        return null;
+    }
+
     /**
      * Get required field with validation.
      *

src/Adapters/README.md

@@ -75,7 +75,7 @@ $result = $adapter->transform($prestaShopData);
 | PrestaShop Field       | BradSearch Field                 | Notes                   |
 | ---------------------- | -------------------------------- | ----------------------- |
 | `remoteId`             | `id`                             | Required                |
-| `sku`                  | `sku`                            | Required                |
+| `sku`                  | `sku`                            | Optional, `''` if none  |
 | `localizedNames`       | `name` (+ locale suffixes)       | Multi-locale support    |
 | `brand.localizedNames` | `brand` (+ locale suffixes)      | Multi-locale support    |
 | `productUrl`           | `productUrl` (+ locale suffixes) | Multi-locale support    |
@@ -135,7 +135,7 @@ PrestaShop variants are transformed to match BradSearch requirements:
 
 The adapter validates input data and throws `ValidationException` for:
 
-- Missing required fields (`remoteId`, `sku`)
+- Missing required fields (`remoteId`)
 - Invalid data structure
 - Missing product array
 

src/Adapters/ShopifyAdapter.php

@@ -680,10 +680,6 @@ private function extractImages(array $imagesData): array
     /**
      * Transform Shopify variants to BradSearch format.
      *
-     * Variant `imageUrl` is intentionally omitted: the parent product's curated
-     * `featuredImage` is the merchant-approved hero image, and we don't want
-     * variant enrichment to swap it for a per-variant photo at search time.
-     *
      * @param array<string> $locales
      * @param array<string, mixed> $translations
      */
@@ -741,6 +737,11 @@ private function transformVariants(
                 $result['basePriceTaxExcluded'] = $basePrice;
             }
 
+            $variantImage = $variant['media']['nodes'][0]['image']['url'] ?? null;
+            if (is_string($variantImage) && $variantImage !== '') {
+                $result['imageUrl'] = ['small' => $variantImage, 'medium' => $variantImage];
+            }
+
             if (! empty($locales)) {
                 $result['attrs'] = $this->transformVariantOptionsWithLocales($options, $locales);
                 foreach ($locales as $locale) {

src/V2/ValueObjects/BulkOperations/Product.php

@@ -36,7 +36,6 @@ public function __construct(
         public array $additionalFields = []
     ) {
         $this->validateId($id);
-        $this->validateSku($sku);
     }
 
     /**
@@ -239,18 +238,4 @@ private function validateId(string $id): void
             );
         }
     }
-
-    /**
-     * @throws InvalidArgumentException
-     */
-    private function validateSku(string $sku): void
-    {
-        if (trim($sku) === '') {
-            throw new InvalidArgumentException(
-                'The product SKU cannot be empty.',
-                'sku',
-                $sku
-            );
-        }
-    }
 }

src/V2/ValueObjects/BulkOperations/ProductBuilder.php

@@ -17,7 +17,7 @@
 final class ProductBuilder
 {
     private ?string $id = null;
-    private ?string $sku = null;
+    private string $sku = '';
     private ?ProductPricing $pricing = null;
     private ?ImageUrl $imageUrl = null;
     private ?bool $inStock = null;
@@ -149,14 +149,6 @@ public function build(): Product
             );
         }
 
-        if ($this->sku === null) {
-            throw new InvalidArgumentException(
-                'Product SKU is required.',
-                'sku',
-                null
-            );
-        }
-
         if ($this->pricing === null) {
             throw new InvalidArgumentException(
                 'Product pricing is required.',
@@ -190,7 +182,7 @@ public function build(): Product
     public function reset(): self
     {
         $this->id = null;
-        $this->sku = null;
+        $this->sku = '';
         $this->pricing = null;
         $this->imageUrl = null;
         $this->inStock = null;

src/V2/ValueObjects/BulkOperations/ProductVariant.php

@@ -34,7 +34,6 @@ public function __construct(
         public array $attrs = []
     ) {
         $this->validateId($id);
-        $this->validateSku($sku);
         $this->validateProductUrl($productUrl);
     }
 
@@ -173,20 +172,6 @@ private function validateId(string $id): void
         }
     }
 
-    /**
-     * @throws InvalidArgumentException
-     */
-    private function validateSku(string $sku): void
-    {
-        if (trim($sku) === '') {
-            throw new InvalidArgumentException(
-                'The variant SKU cannot be empty.',
-                'sku',
-                $sku
-            );
-        }
-    }
-
     /**
      * @throws InvalidArgumentException
      */