chore: synced file(s) with sumup/apis

src/Sales/Sales.php

@@ -0,0 +1,182 @@
+<?php
+
+declare(strict_types=1);
+
+namespace SumUp\Sales;
+
+namespace SumUp\Services;
+
+use SumUp\HttpClient\HttpClientInterface;
+use SumUp\HttpClient\RequestHeaders;
+use SumUp\HttpClient\RequestOptions;
+use SumUp\RequestEncoder;
+use SumUp\ResponseDecoder;
+
+/**
+ * Query parameters for SalesListSalesV10Params.
+ *
+ * @package SumUp\Services
+ */
+class SalesListSalesV10Params
+{
+    /**
+     * Pagination token for subsequent requests. Should only be set by clients if they have
+     * received a token in the previous response, and this request is an immediate follow-up
+     * request to that response to load the subsequent page. Clients should treat this as an
+     * opaque token and should not attempt to parse it in any way.
+     *
+     * @var string|null
+     */
+    public ?string $paginationToken = null;
+
+    /**
+     * Maximum number of results per page.
+     *
+     * @var int|null
+     */
+    public ?int $paginationLimit = null;
+
+}
+
+/**
+ * Class Sales
+ *
+ * Operations related to reading sales data.
+ *
+ * @package SumUp\Services
+ */
+class Sales implements SumUpService
+{
+    /**
+     * The client for the http communication.
+     *
+     * @var HttpClientInterface
+     */
+    protected HttpClientInterface $client;
+
+    /**
+     * The access token needed for authentication for the services.
+     *
+     * @var string
+     */
+    protected string $accessToken;
+
+    /**
+     * Sales constructor.
+     *
+     * @param HttpClientInterface $client
+     * @param string $accessToken
+     */
+    public function __construct(HttpClientInterface $client, string $accessToken)
+    {
+        $this->client = $client;
+        $this->accessToken = $accessToken;
+    }
+
+    /**
+     * Gets a sale
+     *
+     * @param string $merchantCode The merchant code.
+     * @param string $saleId The sale ID.
+     * @param RequestOptions|null $requestOptions Optional typed request options
+     *
+     * @return \SumUp\Types\Sale
+     * @throws \SumUp\Exception\ApiException
+     * @throws \SumUp\Exception\UnexpectedApiException
+     * @throws \SumUp\Exception\ConnectionException
+     * @throws \SumUp\Exception\SDKException
+     */
+    public function getSaleV10(string $merchantCode, string $saleId, ?RequestOptions $requestOptions = null): \SumUp\Types\Sale
+    {
+        $path = sprintf('/v1.0/merchants/%s/sales/%s', rawurlencode((string) $merchantCode), rawurlencode((string) $saleId));
+        $payload = [];
+        $headers = RequestHeaders::build($this->accessToken, $requestOptions);
+
+        $response = $this->client->send('GET', $path, $payload, $headers, $requestOptions);
+
+        return ResponseDecoder::decodeOrThrow($response, \SumUp\Types\Sale::class, [
+            '401' => ['type' => 'class', 'class' => \SumUp\Types\ProblemV10::class],
+            '403' => ['type' => 'class', 'class' => \SumUp\Types\ProblemV10::class],
+            '404' => ['type' => 'class', 'class' => \SumUp\Types\ProblemV10::class],
+            '412' => ['type' => 'class', 'class' => \SumUp\Types\ProblemV10::class],
+        ], 'GET', $path);
+    }
+
+    /**
+     * Lists sales
+     *
+     * @param string $merchantCode The merchant code.
+     * @param SalesListSalesV10Params|null $queryParams Optional query string parameters
+     * @param RequestOptions|null $requestOptions Optional typed request options
+     *
+     * @return \SumUp\Types\SalePage
+     * @throws \SumUp\Exception\ApiException
+     * @throws \SumUp\Exception\UnexpectedApiException
+     * @throws \SumUp\Exception\ConnectionException
+     * @throws \SumUp\Exception\SDKException
+     */
+    public function listSalesV10(string $merchantCode, ?SalesListSalesV10Params $queryParams = null, ?RequestOptions $requestOptions = null): \SumUp\Types\SalePage
+    {
+        $path = sprintf('/v1.0/merchants/%s/sales', rawurlencode((string) $merchantCode));
+        if ($queryParams !== null) {
+            $queryParamsData = [];
+            if (isset($queryParams->paginationToken)) {
+                $queryParamsData['pagination_token'] = $queryParams->paginationToken;
+            }
+            if (isset($queryParams->paginationLimit)) {
+                $queryParamsData['pagination_limit'] = $queryParams->paginationLimit;
+            }
+            if (!empty($queryParamsData)) {
+                $queryString = http_build_query($queryParamsData);
+                if (!empty($queryString)) {
+                    $path .= '?' . $queryString;
+                }
+            }
+        }
+        $payload = [];
+        $headers = RequestHeaders::build($this->accessToken, $requestOptions);
+
+        $response = $this->client->send('GET', $path, $payload, $headers, $requestOptions);
+
+        return ResponseDecoder::decodeOrThrow($response, \SumUp\Types\SalePage::class, [
+            '400' => ['type' => 'class', 'class' => \SumUp\Types\ProblemV10::class],
+            '401' => ['type' => 'class', 'class' => \SumUp\Types\ProblemV10::class],
+            '403' => ['type' => 'class', 'class' => \SumUp\Types\ProblemV10::class],
+            '412' => ['type' => 'class', 'class' => \SumUp\Types\ProblemV10::class],
+        ], 'GET', $path);
+    }
+
+    /**
+     * Searches sales
+     *
+     * @param string $merchantCode The merchant code.
+     * @param \SumUp\Types\SaleSearchRequest|array<string, mixed> $body Required request payload
+     * @param RequestOptions|null $requestOptions Optional typed request options
+     *
+     * @return \SumUp\Types\SaleSearchResponse
+     * @throws \SumUp\Exception\ApiException
+     * @throws \SumUp\Exception\UnexpectedApiException
+     * @throws \SumUp\Exception\ConnectionException
+     * @throws \SumUp\Exception\SDKException
+     */
+    public function searchSalesV10(string $merchantCode, \SumUp\Types\SaleSearchRequest|array $body, ?RequestOptions $requestOptions = null): \SumUp\Types\SaleSearchResponse
+    {
+        $path = sprintf('/v1.0/merchants/%s/sales/search', rawurlencode((string) $merchantCode));
+        $payload = [];
+        $requestBody = $body;
+        if (is_array($requestBody)) {
+            $requestBody = \SumUp\Types\SaleSearchRequest::fromArray($requestBody);
+        }
+        $payload = RequestEncoder::encode($requestBody);
+        $headers = RequestHeaders::build($this->accessToken, $requestOptions);
+
+        $response = $this->client->send('POST', $path, $payload, $headers, $requestOptions);
+
+        return ResponseDecoder::decodeOrThrow($response, \SumUp\Types\SaleSearchResponse::class, [
+            '400' => ['type' => 'class', 'class' => \SumUp\Types\ProblemV10::class],
+            '401' => ['type' => 'class', 'class' => \SumUp\Types\ProblemV10::class],
+            '403' => ['type' => 'class', 'class' => \SumUp\Types\ProblemV10::class],
+            '412' => ['type' => 'class', 'class' => \SumUp\Types\ProblemV10::class],
+        ], 'POST', $path);
+    }
+}

src/Types/BasePerson.php

@@ -46,14 +46,7 @@ class BasePerson
     public ?string $familyName = null;
 
     /**
-     * Middle name(s) of the End-User. Note that in some cultures, people can have multiple middle names; all can be present, with the names being separated by space characters. Also note that in some cultures, middle names are not used.
-     *
-     * @var string|null
-     */
-    public ?string $middleName = null;
-
-    /**
-     * The (mobile) phone number of the individual (used for verification) in [E.164](https://en.wikipedia.org/wiki/E.164) format.
+     * A publicly available phone number in [E.164](https://en.wikipedia.org/wiki/E.164) format.
      *
      * @var string|null
      */
@@ -67,14 +60,14 @@ class BasePerson
     public ?array $relationships = null;
 
     /**
-     * Details about the ownership relationship between the Person and the Merchant. This is only set if the Person has a relationship of type `owner`.
      *
      * @var Ownership|null
      */
     public ?Ownership $ownership = null;
 
     /**
-     * The address of the individual.
+     * An address somewhere in the world. The address fields used depend on the country conventions. For example, in Great Britain, `city` is `post_town`. In the United States, the top-level administrative unit used in addresses is `state`, whereas in Chile it's `region`.
+     * Whether an address is valid or not depends on whether the locally required fields are present. Fields not supported in a country will be ignored.
      *
      * @var Address|null
      */
@@ -88,7 +81,9 @@ class BasePerson
     public ?array $identifiers = null;
 
     /**
-     * The Alpha-2 ISO code of the country where the Person is a citizen.
+     * An [ISO3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2)
+     * country code. This definition users `oneOf` with a two-character string
+     * type to allow for support of future countries in client code.
      *
      * @var string|null
      */

src/Types/CategoryV10.php

@@ -0,0 +1,26 @@
+<?php
+
+declare(strict_types=1);
+
+namespace SumUp\Types;
+
+/**
+ * A category a line belongs to.
+ */
+class CategoryV10
+{
+    /**
+     * The category id. Usually a UUID, but not always (legacy cases).
+     *
+     * @var string
+     */
+    public string $id;
+
+    /**
+     * The category name.
+     *
+     * @var string
+     */
+    public string $name;
+
+}

src/Types/DiscountLine.php

@@ -0,0 +1,80 @@
+<?php
+
+declare(strict_types=1);
+
+namespace SumUp\Types;
+
+/**
+ * Object representing information about single discount line.
+ */
+class DiscountLine
+{
+    /**
+     * An id used to associate a discount line with a specific discount.
+     * Since we can apply multiple discounts (e.g. 2x 10% whole cart off)
+     * we need to be able to identify which discount line belongs to which cart discount.
+     * Recommended to use UUID identifiers.
+     *
+     * @var string|null
+     */
+    public ?string $id = null;
+
+    /**
+     * A description or reason of the discount.
+     *
+     * @var string|null
+     */
+    public ?string $description = null;
+
+    /**
+     * Specifies where discount was applied by user (either merchant or consumer):
+     * - CART: Applied to the whole cart (calculated and distributed per sale item)
+     * - ITEM: Applied to specific sale item
+     * *Accepted values:* ["ITEM", "CART"].
+     *
+     * @var string
+     */
+    public string $level;
+
+    /**
+     * The source of discount. Exactly one property must be set.
+     *
+     * @var DiscountSource
+     */
+    public DiscountSource $source;
+
+    /**
+     * The value type of the discount, either a percentage based or absolute monetary value.
+     * It is required that only one of the following is set:
+     * - absolute
+     * - percentage.
+     *
+     * @var DiscountValue
+     */
+    public DiscountValue $value;
+
+    /**
+     * The net amount of the discount.
+     * The value of the amount in minor units of the currency according to the Sale.currency.scale.
+     *
+     * @var int
+     */
+    public int $netAmount;
+
+    /**
+     * The gross amount of the discount.
+     * The value of the amount in minor units of the currency according to the Sale.currency.scale.
+     *
+     * @var int
+     */
+    public int $grossAmount;
+
+    /**
+     * The tax amount of the discount.
+     * The value of the amount in minor units of the currency according to the Sale.currency.scale.
+     *
+     * @var int
+     */
+    public int $taxAmount;
+
+}

src/Types/DiscountSource.php

@@ -0,0 +1,47 @@
+<?php
+
+declare(strict_types=1);
+
+namespace SumUp\Types;
+
+/**
+ * The source of discount. Exactly one property must be set.
+ */
+class DiscountSource
+{
+    /**
+     * Discount created ad-hoc on device during checkout.
+     *
+     * @var DiscountSourceAdHoc|null
+     */
+    public ?DiscountSourceAdHoc $adHoc = null;
+
+    /**
+     * Preset discount applied manually on the POS.
+     *
+     * @var DiscountSourceBasic|null
+     */
+    public ?DiscountSourceBasic $basic = null;
+
+    /**
+     * Discount applied manually when entering a coupon code at checkout.
+     *
+     * @var DiscountSourceCoupon|null
+     */
+    public ?DiscountSourceCoupon $coupon = null;
+
+    /**
+     * Discount applied automatically when cart is updated based on preset promotions.
+     *
+     * @var DiscountSourceOffer|null
+     */
+    public ?DiscountSourceOffer $offer = null;
+
+    /**
+     * Discount applied when redeeming a reward from the merchant's loyalty scheme.
+     *
+     * @var DiscountSourceLoyalty|null
+     */
+    public ?DiscountSourceLoyalty $loyalty = null;
+
+}