Merge pull request #15 from aligent/feature/orders-v3

Feature/orders v3

README.md

@@ -62,8 +62,8 @@ Running tests: `composer run-script test`
 
 #### Orders (V3)
 
-- ☐ Transactions
-- ☐ Order Refunds
+- ☑️ Transactions
+- ☑️ Order Refunds
 
 #### Payment Methods
 

RELEASE_NOTES.md

@@ -1,13 +1,8 @@
 #### New Features
 
-Add support for the [Themes API](https://developer.bigcommerce.com/api-reference/store-management/themes)
+Add support for the [Orders v3 API](https://developer.bigcommerce.com/api-reference/store-management/order-transactions)
 
 Includes
 
-- Themes
-- Theme Actions
-- Theme Jobs
-
-#### Code Improvements
-
-- Refactor PaginatedResponse to be simpler to implement
+- Transactions
+- Order refunds

src/BigCommerce/Client.php

@@ -2,6 +2,7 @@
 
 namespace BigCommerce\ApiV3;
 
+use BigCommerce\ApiV3\Orders\OrdersApi;
 use BigCommerce\ApiV3\Customers\CustomersApi;
 use BigCommerce\ApiV3\PriceLists\PriceListsApi;
 use BigCommerce\ApiV3\Themes\ThemesApi;
@@ -122,4 +123,9 @@ public function theme(string $uuid): ThemesApi
         $api->setUuid($uuid);
         return $api;
     }
+
+    public function order(int $orderId): OrdersApi
+    {
+        return new OrdersApi($this, $orderId);
+    }
 }

src/BigCommerce/Orders/OrdersApi.php

@@ -0,0 +1,31 @@
+<?php
+
+namespace BigCommerce\ApiV3\Orders;
+
+use BigCommerce\ApiV3\Api\V3ApiBase;
+use BigCommerce\ApiV3\ResponseModels\Order\TransactionsResponse;
+
+class OrdersApi extends V3ApiBase
+{
+    private const ORDER_ENDPOINT = 'orders/%d';
+    private const TRANSACTIONS_ENDPOINT = self::ORDER_ENDPOINT . '/transactions';
+
+    public function transactions(): TransactionsResponse
+    {
+        $response = $this->getClient()->getRestClient()->get(
+            sprintf(self::TRANSACTIONS_ENDPOINT, $this->getResourceId())
+        );
+
+        return new TransactionsResponse($response);
+    }
+
+    public function refunds(): RefundsApi
+    {
+        return new RefundsApi($this->getClient(), null, $this->getResourceId());
+    }
+
+    public function refund(): RefundsApi
+    {
+        return $this->refunds();
+    }
+}

src/BigCommerce/Orders/RefundsApi.php

@@ -0,0 +1,56 @@
+<?php
+
+namespace BigCommerce\ApiV3\Orders;
+
+use BigCommerce\ApiV3\Api\V3ApiBase;
+use BigCommerce\ApiV3\ResourceModels\Order\OrderRefundItem;
+use BigCommerce\ApiV3\ResponseModels\Order\RefundQuoteResponse;
+use BigCommerce\ApiV3\ResponseModels\Order\RefundResponse;
+use BigCommerce\ApiV3\ResponseModels\Order\RefundsResponse;
+use GuzzleHttp\RequestOptions;
+
+class RefundsApi extends V3ApiBase
+{
+    private const ORDER_REFUNDS_ENDPOINT = 'orders/%d/payment_actions';
+    private const REFUND_QUOTE_ENDPOINT  = self::ORDER_REFUNDS_ENDPOINT . '/refund_quotes';
+    private const REFUND_ENDPOINT        = self::ORDER_REFUNDS_ENDPOINT . '/refunds';
+
+    /**
+     * @param OrderRefundItem[] $items
+     * @param string $reason
+     * @return RefundResponse
+     * @throws \GuzzleHttp\Exception\GuzzleException
+     */
+    public function create(array $items, string $reason): RefundResponse
+    {
+        $response = $this->getClient()->getRestClient()->post(
+            sprintf(self::REFUND_ENDPOINT, $this->getParentResourceId()),
+            [
+                RequestOptions::JSON => []
+            ]
+        );
+
+        return new RefundResponse($response);
+    }
+
+    public function createQuote(): RefundQuoteResponse
+    {
+        $response = $this->getClient()->getRestClient()->post(
+            sprintf(self::REFUND_QUOTE_ENDPOINT, $this->getParentResourceId()),
+            [
+                RequestOptions::JSON => []
+            ]
+        );
+
+        return new RefundQuoteResponse($response);
+    }
+
+    public function getAll(): RefundsResponse
+    {
+        $response = $this->getClient()->getRestClient()->get(
+            sprintf(self::REFUND_ENDPOINT, $this->getParentResourceId())
+        );
+
+        return new RefundsResponse($response);
+    }
+}

src/BigCommerce/ResourceModels/Order/OrderRefundItem.php

@@ -0,0 +1,19 @@
+<?php
+
+namespace BigCommerce\ApiV3\ResourceModels\Order;
+
+use BigCommerce\ApiV3\ResourceModels\ResourceModel;
+
+class OrderRefundItem extends ResourceModel
+{
+    public const ITEM_TYPE__SHIPPING = 'SHIPPING';
+    public const ITEM_TYPE__HANDLING = 'HANDLING';
+    public const ITEM_TYPE__PRODUCT = 'PRODUCT';
+    public const ITEM_TYPE__GIFT_WRAPPING = 'GIFT_WRAPPING';
+
+    public string $item_type;
+    public int $item_id;
+    public ?float $amount;
+    public ?float $quantity;
+    public ?string $reason;
+}

src/BigCommerce/ResourceModels/Order/Refund.php

@@ -0,0 +1,29 @@
+<?php
+
+namespace BigCommerce\ApiV3\ResourceModels\Order;
+
+use BigCommerce\ApiV3\ResourceModels\ResourceModel;
+use stdClass;
+
+class Refund extends ResourceModel
+{
+    public int $id;
+    public int $order_id;
+    public int $user_id;
+    public string $created;
+    public string $reason;
+    public float $total_amount;
+    public float $total_tax;
+    /**
+     * @var OrderRefundItem[]
+     */
+    public array $items;
+    public array $payments;
+
+    public function __construct(?stdClass $optionObject = null)
+    {
+        $this->items = array_map(fn($i) => new OrderRefundItem($i), $optionObject->items);
+        unset($optionObject->items);
+        parent::__construct($optionObject);
+    }
+}

src/BigCommerce/ResourceModels/Order/RefundQuote.php

@@ -0,0 +1,16 @@
+<?php
+
+namespace BigCommerce\ApiV3\ResourceModels\Order;
+
+use BigCommerce\ApiV3\ResourceModels\ResourceModel;
+
+class RefundQuote extends ResourceModel
+{
+    public int $order_id;
+    public float $total_refund_amount;
+    public float $total_refund_tax_amount;
+    public float $rounding;
+    public float $adjustment;
+    public bool $tax_inclusive;
+    public array $refund_methods;
+}

src/BigCommerce/ResourceModels/Order/Transaction.php

@@ -0,0 +1,31 @@
+<?php
+
+namespace BigCommerce\ApiV3\ResourceModels\Order;
+
+use BigCommerce\ApiV3\ResourceModels\ResourceModel;
+
+class Transaction extends ResourceModel
+{
+    public int $id;
+    public int $order_id;
+    public string $event;
+    public string $method;
+    public int $amount;
+    public string $currency;
+    public string $gateway;
+    public string $gateway_transaction_id;
+    public string $status;
+    public bool $test;
+    public bool $fraud_review;
+    public ?int $reference_transaction_id;
+    public string $date_created;
+    public object $avs_result;
+    public object $cvv_result;
+    public object $credit_card;
+    public object $gift_certificate;
+    public object $store_credit;
+    public object $offline;
+    public object $custom;
+    public string $payment_instrument_token;
+    public string $payment_method_id;
+}

src/BigCommerce/ResponseModels/Order/RefundQuoteResponse.php

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

src/BigCommerce/ResponseModels/Order/RefundResponse.php

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

src/BigCommerce/ResponseModels/Order/RefundsResponse.php

@@ -0,0 +1,21 @@
+<?php
+
+namespace BigCommerce\ApiV3\ResponseModels\Order;
+
+use BigCommerce\ApiV3\ResourceModels\Order\Refund;
+use BigCommerce\ApiV3\ResponseModels\PaginatedResponse;
+
+class RefundsResponse extends PaginatedResponse
+{
+    /**
+     * @return Refund[]
+     */
+    public function refunds(): array
+    {
+        return $this->getData();
+    }
+    protected function resourceClass(): string
+    {
+        return Refund::class;
+    }
+}

src/BigCommerce/ResponseModels/Order/TransactionsResponse.php

@@ -0,0 +1,25 @@
+<?php
+
+namespace BigCommerce\ApiV3\ResponseModels\Order;
+
+use BigCommerce\ApiV3\Api\FetchAllPages;
+use BigCommerce\ApiV3\ResourceModels\Order\Transaction;
+use BigCommerce\ApiV3\ResponseModels\PaginatedResponse;
+
+class TransactionsResponse extends PaginatedResponse
+{
+    use FetchAllPages;
+
+    /**
+     * @return Transaction[]
+     */
+    public function getTransactions(): array
+    {
+        return $this->getData();
+    }
+
+    protected function resourceClass(): string
+    {
+        return Transaction::class;
+    }
+}

tests/BigCommerce/Orders/OrdersApiTest.php

@@ -0,0 +1,28 @@
+<?php
+
+namespace BigCommerce\Tests\Orders;
+
+use BigCommerce\ApiV3\Orders\OrdersApi;
+use BigCommerce\Tests\BigCommerceApiTest;
+
+class OrdersApiTest extends BigCommerceApiTest
+{
+    public function testCanGetOrdersApi()
+    {
+        $orderId = 123;
+
+        $ordersApi = $this->getApi()->order($orderId);
+        $this->assertInstanceOf(OrdersApi::class, $ordersApi);
+        $this->assertEquals($orderId, $ordersApi->getResourceId());
+    }
+
+    public function testCanGetOrderTransactions()
+    {
+        $this->setReturnData('orders__transactions__get.json');
+        $orderId = 121;
+
+        $transactionsResponse = $this->getApi()->order($orderId)->transactions();
+        $this->assertCount(1, $transactionsResponse->getTransactions());
+        $this->assertEquals(1, $transactionsResponse->getPagination()->total);
+    }
+}