Merge pull request #49 from aligent/feature/implement-cart-api

Feature/implement cart api

RELEASE_NOTES.md

@@ -1,6 +1,9 @@
 ### New Features
 
-Allow the use of [parameters in ProductsApi::Get](https://developer.bigcommerce.com/api-reference/store-management/catalog/products/getproductbyid).
+- Implement the [Cart API](https://developer.bigcommerce.com/api-reference/store-management/carts/cart/createacart).
+- Implement the [Cart Items API](https://developer.bigcommerce.com/api-reference/store-management/carts/cart-items/addcartlineitem)
+- Implement the [Cart Redirect URLS API](https://developer.bigcommerce.com/api-reference/store-management/carts/cart-redirect-urls/createcartredirecturl)
+- Allow the use of [parameters in ProductsApi::Get](https://developer.bigcommerce.com/api-reference/store-management/catalog/products/getproductbyid).
 
 Here's an example using PHP 8:
 
@@ -12,3 +15,4 @@ $product = $api->catalog()->product(123)->get(include_fields: ['description', 's
 
 Fix issue with ProductVariant::sku_id not being nullable #47 (thanks @Yorgv)
 
+

src/BigCommerce/Api/Carts/CartItemsApi.php

@@ -0,0 +1,70 @@
+<?php
+
+namespace BigCommerce\ApiV3\Api\Carts;
+
+use BigCommerce\ApiV3\Api\Generic\DeleteResource;
+use BigCommerce\ApiV3\Api\Generic\UuidResourceWithUuidParentApi;
+use BigCommerce\ApiV3\ResourceModels\Cart\CartItem;
+use BigCommerce\ApiV3\ResponseModels\Cart\CartResponse;
+use GuzzleHttp\RequestOptions;
+
+class CartItemsApi extends UuidResourceWithUuidParentApi
+{
+    use DeleteResource;
+
+    private const CARTS_ENDPOINT = 'carts/%s/items';
+    private const CART_ENDPOINT  = 'carts/%s/items/%s';
+
+    /**
+     * Create a direct link to a Cart.
+     */
+    public const INCLUDE_REDIRECT_URLS = 'redirect_urls';
+
+    /**
+     *  The Cart returns an abbreviated result. Use this to return physical items product options.
+     */
+    public const INCLUDE_PHYSICAL_ITEMS = 'line_items.physical_items.options';
+
+    /**
+     * The Cart returns an abbreviated result. Use this to return digital items product options.
+     */
+    public const INCLUDE_DIGITAL_ITEMS = 'line_items.digital_items.options';
+
+    public function add(CartItem $cartItem, ?string $include = null): CartResponse
+    {
+        $query = $include ? ['include' => $include] : [];
+        $response = $this->getClient()->getRestClient()->post(
+            $this->multipleResourceUrl(),
+            [
+                RequestOptions::JSON => $cartItem,
+                RequestOptions::QUERY => $query,
+            ]
+        );
+
+        return new CartResponse($response);
+    }
+
+    public function update(CartItem $cartItem, ?string $include = null): CartResponse
+    {
+        $query = $include ? ['include' => $include] : [];
+        $response = $this->getClient()->getRestClient()->put(
+            $this->singleResourceUrl(),
+            [
+                RequestOptions::JSON => $cartItem,
+                RequestOptions::QUERY => $query,
+            ]
+        );
+
+        return new CartResponse($response);
+    }
+
+    public function multipleResourceUrl(): string
+    {
+        return sprintf(self::CARTS_ENDPOINT, $this->getParentUuid());
+    }
+
+    public function singleResourceUrl(): string
+    {
+        return sprintf(self::CART_ENDPOINT, $this->getParentUuid(), $this->getUuid());
+    }
+}

src/BigCommerce/Api/Carts/CartRedirectUrlsApi.php

@@ -0,0 +1,20 @@
+<?php
+
+namespace BigCommerce\ApiV3\Api\Carts;
+
+use BigCommerce\ApiV3\Api\Generic\UuidResourceWithUuidParentApi;
+use BigCommerce\ApiV3\ResponseModels\Cart\CartRedirectUrlsResponse;
+
+class CartRedirectUrlsApi extends UuidResourceWithUuidParentApi
+{
+    private const REDIRECT_URL = 'carts/%d/redirect_urls';
+
+    public function create(): CartRedirectUrlsResponse
+    {
+        $response = $this->getClient()->getRestClient()->put(
+            sprintf(self::REDIRECT_URL, $this->getParentUuid())
+        );
+
+        return new CartRedirectUrlsResponse($response);
+    }
+}

src/BigCommerce/Api/Carts/CartsApi.php

@@ -0,0 +1,77 @@
+<?php
+
+namespace BigCommerce\ApiV3\Api\Carts;
+
+use BigCommerce\ApiV3\Api\Generic\CreateResource;
+use BigCommerce\ApiV3\Api\Generic\DeleteResource;
+use BigCommerce\ApiV3\Api\Generic\GetResource;
+use BigCommerce\ApiV3\Api\Generic\UuidResourceApi;
+use BigCommerce\ApiV3\ResourceModels\Cart\Cart;
+use BigCommerce\ApiV3\ResponseModels\Cart\CartResponse;
+use GuzzleHttp\RequestOptions;
+
+class CartsApi extends UuidResourceApi
+{
+    use GetResource;
+    use CreateResource;
+    use DeleteResource;
+
+    private const CARTS_ENDPOINT = 'carts';
+    private const CART_ENDPOINT  = 'carts/%s';
+
+    public function get(): CartResponse
+    {
+        return new CartResponse($this->getResource());
+    }
+
+    public function create(Cart $cart): CartResponse
+    {
+        return new CartResponse($this->createResource($cart));
+    }
+
+    public function updateCustomerId(int $customerId): CartResponse
+    {
+        $response = $this->getClient()->getRestClient()->put(
+            $this->singleResourceUrl(),
+            [
+                RequestOptions::JSON => ['customer_id' => $customerId],
+            ]
+        );
+
+        return new CartResponse($response);
+    }
+
+    public function singleResourceUrl(): string
+    {
+        return sprintf(self::CART_ENDPOINT, $this->getUuid());
+    }
+
+    public function multipleResourceUrl(): string
+    {
+        return self::CARTS_ENDPOINT;
+    }
+
+    public function item(string $id): CartItemsApi
+    {
+        $itemsApi = $this->items();
+        $itemsApi->setUuid($id);
+
+        return $itemsApi;
+    }
+
+    public function items(): CartItemsApi
+    {
+        $itemsApi = new CartItemsApi($this->getClient());
+        $itemsApi->setParentUuid($this->getUuid());
+
+        return $itemsApi;
+    }
+
+    public function redirectUrls(): CartRedirectUrlsApi
+    {
+        $redirectsApi = new CartRedirectUrlsApi();
+        $redirectsApi->setParentUuid($this->getUuid());
+
+        return $redirectsApi;
+    }
+}

src/BigCommerce/Api/Generic/UuidResourceWithUuidParentApi.php

@@ -0,0 +1,18 @@
+<?php
+
+namespace BigCommerce\ApiV3\Api\Generic;
+
+abstract class UuidResourceWithUuidParentApi extends UuidResourceApi
+{
+    private string $parentUuid;
+
+    public function getParentUuid(): string
+    {
+        return $this->parentUuid;
+    }
+
+    public function setParentUuid(string $parentUuid): void
+    {
+        $this->parentUuid = $parentUuid;
+    }
+}

src/BigCommerce/Client.php

@@ -2,6 +2,7 @@
 
 namespace BigCommerce\ApiV3;
 
+use BigCommerce\ApiV3\Api\Carts\CartsApi;
 use BigCommerce\ApiV3\Api\Catalog\CatalogApi;
 use BigCommerce\ApiV3\Api\Orders\OrdersApi;
 use BigCommerce\ApiV3\Api\Customers\CustomersApi;
@@ -129,6 +130,18 @@ public function theme(string $uuid): ThemesApi
         return $api;
     }
 
+    public function carts(): CartsApi
+    {
+        return new CartsApi($this);
+    }
+
+    public function cart(string $uuid): CartsApi
+    {
+        $api = $this->carts();
+        $api->setUuid($uuid);
+        return $api;
+    }
+
     public function order(int $orderId): OrdersApi
     {
         return new OrdersApi($this, $orderId);

src/BigCommerce/ResourceModels/Cart/Cart.php

@@ -0,0 +1,25 @@
+<?php
+
+namespace BigCommerce\ApiV3\ResourceModels\Cart;
+
+use BigCommerce\ApiV3\ResourceModels\ResourceModel;
+
+class Cart extends ResourceModel
+{
+    public string $id;
+    public string $parent_id;
+    public int $customer_id;
+    public string $email;
+    public $currency;
+    public bool $tax_included;
+    public float $base_amount;
+    public float $discount_amount;
+    public float $cart_amount;
+    public array $coupons;
+    public array $discounts;
+    public $line_items;
+    public string $created_time;
+    public string $updated_time;
+    public int $channel_id;
+    public string $locale;
+}

src/BigCommerce/ResourceModels/Cart/CartItem.php

@@ -0,0 +1,12 @@
+<?php
+
+namespace BigCommerce\ApiV3\ResourceModels\Cart;
+
+use BigCommerce\ApiV3\ResourceModels\ResourceModel;
+
+class CartItem extends ResourceModel
+{
+    public array $line_items;
+    public array $gift_certificates;
+    public array $custom_items;
+}

src/BigCommerce/ResourceModels/Cart/CartRedirectUrls.php

@@ -0,0 +1,11 @@
+<?php
+
+namespace BigCommerce\ApiV3\ResourceModels\Cart;
+
+use BigCommerce\ApiV3\ResourceModels\ResourceModel;
+
+class CartRedirectUrls extends ResourceModel
+{
+    public string $cart_url;
+    public string $checkout_url;
+}

src/BigCommerce/ResponseModels/Cart/CartRedirectUrlsResponse.php

@@ -0,0 +1,22 @@
+<?php
+
+namespace BigCommerce\ApiV3\ResponseModels\Cart;
+
+use BigCommerce\ApiV3\ResourceModels\Cart\CartRedirectUrls;
+use BigCommerce\ApiV3\ResponseModels\SingleResourceResponse;
+use stdClass;
+
+class CartRedirectUrlsResponse extends SingleResourceResponse
+{
+    private CartRedirectUrls $cartRedirectUrls;
+
+    public function getCartRedirectUrls(): CartRedirectUrls
+    {
+        return $this->cartRedirectUrls;
+    }
+
+    protected function addData(stdClass $rawData): void
+    {
+        $this->cartRedirectUrls = new CartRedirectUrls($rawData);
+    }
+}

src/BigCommerce/ResponseModels/Cart/CartResponse.php

@@ -0,0 +1,22 @@
+<?php
+
+namespace BigCommerce\ApiV3\ResponseModels\Cart;
+
+use BigCommerce\ApiV3\ResourceModels\Cart\Cart;
+use BigCommerce\ApiV3\ResponseModels\SingleResourceResponse;
+use stdClass;
+
+class CartResponse extends SingleResourceResponse
+{
+    private Cart $cart;
+
+    public function getCart(): Cart
+    {
+        return $this->cart;
+    }
+
+    protected function addData(stdClass $rawData): void
+    {
+        $this->cart = new Cart($rawData);
+    }
+}

tests/BigCommerce/Api/Carts/CartItemsApiTest.php

@@ -0,0 +1,40 @@
+<?php
+
+namespace BigCommerce\Tests\Api\Carts;
+
+use BigCommerce\ApiV3\Api\Carts\CartItemsApi;
+use BigCommerce\ApiV3\ResourceModels\Cart\CartItem;
+use BigCommerce\Tests\BigCommerceApiTest;
+
+class CartItemsApiTest extends BigCommerceApiTest
+{
+    public function testCanAddCartLineItem()
+    {
+        $this->setReturnData('carts_get.json', 201);
+        $id = 'aae435b7-e8a4-48f2-abcd-ad0675dc3123';
+
+        $lineItem = new CartItem();
+        $lineItem->line_items[] = [
+            "sku"        => "made-up",
+            "name"       => "My product",
+            "quantity"   => 33,
+            "list_price" => 55
+        ];
+
+        $this->getApi()->cart($id)->items()->add($lineItem, CartItemsApi::INCLUDE_REDIRECT_URLS);
+
+        $this->assertEquals("carts/$id/items", $this->getLastRequest()->getUri()->getPath());
+    }
+
+    public function testCanDeleteCartLineItem()
+    {
+        $this->setReturnData('blank.json', 204);
+        $id = 'aae435b7-e8a4-48f2-abcd-ad0675dc3123';
+        $lineItemId = '7c0afc28-abcd-42ad-afe6-7a87d6923bc5';
+
+        $this->getApi()->cart($id)->item($lineItemId)->delete();
+        $lastRequest = $this->getLastRequest();
+        $this->assertEquals("carts/$id/items/$lineItemId", $lastRequest->getUri()->getPath());
+        $this->assertEquals('DELETE', $lastRequest->getMethod());
+    }
+}