[GraphQl] Single mutation for adding different types of products to the shopping cart

app/code/Magento/CatalogGraphQl/Model/Resolver/Product/CustomizableEnteredOptionValueUid.php

@@ -45,6 +45,9 @@ public function resolve(
         array $value = null,
         array $args = null
     ) {
+        if (isset($value['uid'])) {
+            return $value['uid'];
+        }
         if (!isset($value['option_id']) || empty($value['option_id'])) {
             throw new GraphQlInputException(__('"option_id" value should be specified.'));
         }

app/code/Magento/CatalogGraphQl/Model/Resolver/Product/CustomizableSelectedOptionValueUid.php

@@ -45,6 +45,9 @@ public function resolve(
         array $value = null,
         array $args = null
     ) {
+        if (isset($value['uid'])) {
+            return $value['uid'];
+        }
         if (!isset($value['option_id']) || empty($value['option_id'])) {
             throw new GraphQlInputException(__('"option_id" value should be specified.'));
         }

app/code/Magento/GraphQl/etc/schema.graphqls

@@ -277,3 +277,8 @@ enum CurrencyEnum @doc(description: "The list of available currency codes") {
     TRL
     XPF
 }
+
+input EnteredOptionInput @doc(description: "Defines a customer-entered option") {
+    uid: ID! @doc(description: "An encoded ID")
+    value: String! @doc(description: "Text the customer entered")
+}

app/code/Magento/Quote/Model/Cart/AddProductsToCart.php

@@ -0,0 +1,225 @@
+<?php
+/**
+ * Copyright © Magento, Inc. All rights reserved.
+ * See COPYING.txt for license details.
+ */
+declare(strict_types=1);
+
+namespace Magento\Quote\Model\Cart;
+
+use Magento\Catalog\Api\ProductRepositoryInterface;
+use Magento\Framework\Exception\NoSuchEntityException;
+use Magento\Quote\Api\CartRepositoryInterface;
+use Magento\Quote\Api\Data\CartInterface;
+use Magento\Quote\Model\Cart\BuyRequest\BuyRequestBuilder;
+use Magento\Quote\Model\Cart\Data\AddProductsToCartOutput;
+use Magento\Quote\Model\MaskedQuoteIdToQuoteIdInterface;
+use Magento\Quote\Model\Quote;
+use Magento\Framework\Message\MessageInterface;
+
+/**
+ * Unified approach to add products to the Shopping Cart.
+ * Client code must validate, that customer is eligible to call service with provided {cartId} and {cartItems}
+ */
+class AddProductsToCart
+{
+    /**#@+
+     * Error message codes
+     */
+    private const ERROR_PRODUCT_NOT_FOUND = 'PRODUCT_NOT_FOUND';
+    private const ERROR_INSUFFICIENT_STOCK = 'INSUFFICIENT_STOCK';
+    private const ERROR_NOT_SALABLE = 'NOT_SALABLE';
+    private const ERROR_UNDEFINED = 'UNDEFINED';
+    /**#@-*/
+
+    /**
+     * List of error messages and codes.
+     */
+    private const MESSAGE_CODES = [
+        'Could not find a product with SKU' => self::ERROR_PRODUCT_NOT_FOUND,
+        'The required options you selected are not available' => self::ERROR_NOT_SALABLE,
+        'Product that you are trying to add is not available.' => self::ERROR_NOT_SALABLE,
+        'This product is out of stock' => self::ERROR_INSUFFICIENT_STOCK,
+        'There are no source items' => self::ERROR_NOT_SALABLE,
+        'The fewest you may purchase is' => self::ERROR_INSUFFICIENT_STOCK,
+        'The most you may purchase is' => self::ERROR_INSUFFICIENT_STOCK,
+        'The requested qty is not available' => self::ERROR_INSUFFICIENT_STOCK,
+    ];
+
+    /**
+     * @var ProductRepositoryInterface
+     */
+    private $productRepository;
+
+    /**
+     * @var array
+     */
+    private $errors = [];
+
+    /**
+     * @var CartRepositoryInterface
+     */
+    private $cartRepository;
+
+    /**
+     * @var MaskedQuoteIdToQuoteIdInterface
+     */
+    private $maskedQuoteIdToQuoteId;
+
+    /**
+     * @var BuyRequestBuilder
+     */
+    private $requestBuilder;
+
+    /**
+     * @param ProductRepositoryInterface $productRepository
+     * @param CartRepositoryInterface $cartRepository
+     * @param MaskedQuoteIdToQuoteIdInterface $maskedQuoteIdToQuoteId
+     * @param BuyRequestBuilder $requestBuilder
+     */
+    public function __construct(
+        ProductRepositoryInterface $productRepository,
+        CartRepositoryInterface $cartRepository,
+        MaskedQuoteIdToQuoteIdInterface $maskedQuoteIdToQuoteId,
+        BuyRequestBuilder $requestBuilder
+    ) {
+        $this->productRepository = $productRepository;
+        $this->cartRepository = $cartRepository;
+        $this->maskedQuoteIdToQuoteId = $maskedQuoteIdToQuoteId;
+        $this->requestBuilder = $requestBuilder;
+    }
+
+    /**
+     * Add cart items to the cart
+     *
+     * @param string $maskedCartId
+     * @param Data\CartItem[] $cartItems
+     * @return AddProductsToCartOutput
+     * @throws NoSuchEntityException Could not find a Cart with provided $maskedCartId
+     */
+    public function execute(string $maskedCartId, array $cartItems): AddProductsToCartOutput
+    {
+        $cartId = $this->maskedQuoteIdToQuoteId->execute($maskedCartId);
+        $cart = $this->cartRepository->get($cartId);
+
+        foreach ($cartItems as $cartItemPosition => $cartItem) {
+            $this->addItemToCart($cart, $cartItem, $cartItemPosition);
+        }
+
+        if ($cart->getData('has_error')) {
+            $errors = $cart->getErrors();
+
+            /** @var MessageInterface $error */
+            foreach ($errors as $error) {
+                $this->addError($error->getText());
+            }
+        }
+
+        if (count($this->errors) !== 0) {
+            /* Revert changes introduced by add to cart processes in case of an error */
+            $cart->getItemsCollection()->clear();
+        }
+
+        return $this->prepareErrorOutput($cart);
+    }
+
+    /**
+     * Adds a particular item to the shopping cart
+     *
+     * @param CartInterface|Quote $cart
+     * @param Data\CartItem $cartItem
+     * @param int $cartItemPosition
+     */
+    private function addItemToCart(CartInterface $cart, Data\CartItem $cartItem, int $cartItemPosition): void
+    {
+        $sku = $cartItem->getSku();
+
+        if ($cartItem->getQuantity() <= 0) {
+            $this->addError(__('The product quantity should be greater than 0')->render());
+
+            return;
+        }
+
+        try {
+            $product = $this->productRepository->get($sku, false, null, true);
+        } catch (NoSuchEntityException $e) {
+            $this->addError(
+                __('Could not find a product with SKU "%sku"', ['sku' => $sku])->render(),
+                $cartItemPosition
+            );
+
+            return;
+        }
+
+        try {
+            $result = $cart->addProduct($product, $this->requestBuilder->build($cartItem));
+            $this->cartRepository->save($cart);
+        } catch (\Throwable $e) {
+            $this->addError(
+                __($e->getMessage())->render(),
+                $cartItemPosition
+            );
+            $cart->setHasError(false);
+
+            return;
+        }
+
+        if (is_string($result)) {
+            $errors = array_unique(explode("\n", $result));
+            foreach ($errors as $error) {
+                $this->addError(__($error)->render(), $cartItemPosition);
+            }
+        }
+    }
+
+    /**
+     * Add order line item error
+     *
+     * @param string $message
+     * @param int $cartItemPosition
+     * @return void
+     */
+    private function addError(string $message, int $cartItemPosition = 0): void
+    {
+        $this->errors[] = new Data\Error(
+            $message,
+            $this->getErrorCode($message),
+            $cartItemPosition
+        );
+    }
+
+    /**
+     * Get message error code.
+     *
+     * TODO: introduce a separate class for getting error code from a message
+     *
+     * @param string $message
+     * @return string
+     */
+    private function getErrorCode(string $message): string
+    {
+        foreach (self::MESSAGE_CODES as $codeMessage => $code) {
+            if (false !== stripos($message, $codeMessage)) {
+                return $code;
+            }
+        }
+
+        /* If no code was matched, return the default one */
+        return self::ERROR_UNDEFINED;
+    }
+
+    /**
+     * Creates a new output from existing errors
+     *
+     * @param CartInterface $cart
+     * @return AddProductsToCartOutput
+     */
+    private function prepareErrorOutput(CartInterface $cart): AddProductsToCartOutput
+    {
+        $output = new AddProductsToCartOutput($cart, $this->errors);
+        $this->errors = [];
+        $cart->setHasError(false);
+
+        return $output;
+    }
+}

app/code/Magento/Quote/Model/Cart/BuyRequest/BuyRequestBuilder.php

@@ -0,0 +1,61 @@
+<?php
+/**
+ * Copyright © Magento, Inc. All rights reserved.
+ * See COPYING.txt for license details.
+ */
+declare(strict_types=1);
+
+namespace Magento\Quote\Model\Cart\BuyRequest;
+
+use Magento\Framework\DataObject;
+use Magento\Framework\DataObjectFactory;
+use Magento\Quote\Model\Cart\Data\CartItem;
+
+/**
+ * Build buy request for adding products to cart
+ */
+class BuyRequestBuilder
+{
+    /**
+     * @var BuyRequestDataProviderInterface[]
+     */
+    private $providers;
+
+    /**
+     * @var DataObjectFactory
+     */
+    private $dataObjectFactory;
+
+    /**
+     * @param DataObjectFactory $dataObjectFactory
+     * @param array $providers
+     */
+    public function __construct(
+        DataObjectFactory $dataObjectFactory,
+        array $providers = []
+    ) {
+        $this->dataObjectFactory = $dataObjectFactory;
+        $this->providers = $providers;
+    }
+
+    /**
+     * Build buy request for adding product to cart
+     *
+     * @see \Magento\Quote\Model\Quote::addProduct
+     * @param CartItem $cartItem
+     * @return DataObject
+     */
+    public function build(CartItem $cartItem): DataObject
+    {
+        $requestData = [
+            ['qty' => $cartItem->getQuantity()]
+        ];
+
+        /** @var BuyRequestDataProviderInterface $provider */
+        foreach ($this->providers as $provider) {
+            $requestData[] = $provider->execute($cartItem);
+        }
+
+        return $this->dataObjectFactory->create(['data' => array_merge(...$requestData)]);
+    }
+}

app/code/Magento/Quote/Model/Cart/BuyRequest/BuyRequestDataProviderInterface.php

@@ -0,0 +1,24 @@
+<?php
+/**
+ * Copyright © Magento, Inc. All rights reserved.
+ * See COPYING.txt for license details.
+ */
+declare(strict_types=1);
+
+namespace Magento\Quote\Model\Cart\BuyRequest;
+
+use Magento\Quote\Model\Cart\Data\CartItem;
+
+/**
+ * Provides data for buy request for different types of products
+ */
+interface BuyRequestDataProviderInterface
+{
+    /**
+     * Provide buy request data from add to cart item request
+     *
+     * @param CartItem $cartItem
+     * @return array
+     */
+    public function execute(CartItem $cartItem): array;
+}