Add Square\Legacy client

src/Legacy/ApiHelper.php

@@ -0,0 +1,174 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Square\Legacy;
+
+use Core\Utils\CoreHelper;
+use Core\Utils\JsonHelper;
+use InvalidArgumentException;
+use stdClass;
+
+/**
+ * API utility class.
+ */
+class ApiHelper
+{
+    /**
+     * @var JsonHelper
+     */
+    private static $jsonHelper;
+
+    public static function getJsonHelper(): JsonHelper
+    {
+        if (self::$jsonHelper == null) {
+            self::$jsonHelper = new JsonHelper([], [], null, 'Square\\Models');
+        }
+        return self::$jsonHelper;
+    }
+
+    /**
+     * Serialize any given mixed value.
+     *
+     * @param mixed $value Any value to be serialized
+     *
+     * @return string|null serialized value
+     */
+    public static function serialize($value): ?string
+    {
+        return CoreHelper::serialize($value);
+    }
+
+    /**
+     * Deserialize a Json string.
+     *
+     * @param string $json A valid Json string
+     *
+     * @return mixed Decoded Json
+     */
+    public static function deserialize(string $json)
+    {
+        return CoreHelper::deserialize($json);
+    }
+
+    /**
+     * Merge headers
+     *
+     * Header names are compared using case-insensitive comparison. This method
+     * preserves the original header name. If the $newHeaders overrides an existing
+     * header, then the new header name (with its casing) is used.
+     */
+    public static function mergeHeaders(array $headers, array $newHeaders): array
+    {
+        $headerKeys = [];
+
+        // Create a map of lower-cased-header-name to original-header-names
+        foreach ($headers as $headerName => $val) {
+            $headerKeys[\strtolower($headerName)] = $headerName;
+        }
+
+        // Override headers with new values
+        foreach ($newHeaders as $headerName => $headerValue) {
+            $lowerCasedName = \strtolower($headerName);
+            if (isset($headerKeys[$lowerCasedName])) {
+                unset($headers[$headerKeys[$lowerCasedName]]);
+            }
+            $headerKeys[$lowerCasedName] = $headerName;
+            $headers[$headerName] = $headerValue;
+        }
+
+        return $headers;
+    }
+
+    /**
+     * Assert if headers array is valid.
+     *
+     * @throws InvalidArgumentException
+     */
+    public static function assertHeaders(array $headers): void
+    {
+        foreach ($headers as $header => $value) {
+            // Validate header name (must be string, must use allowed chars)
+            // Ref: https://tools.ietf.org/html/rfc7230#section-3.2
+            if (!is_string($header)) {
+                throw new InvalidArgumentException(sprintf(
+                    'Header name must be a string but %s provided.',
+                    is_object($header) ? get_class($header) : gettype($header)
+                ));
+            }
+
+            if (preg_match('/^[a-zA-Z0-9\'`#$%&*+.^_|~!-]+$/', $header) !== 1) {
+                throw new InvalidArgumentException(
+                    sprintf(
+                        '"%s" is not a valid header name.',
+                        $header
+                    )
+                );
+            }
+
+            // Validate value (must be scalar)
+            if (!is_scalar($value) || null === $value) {
+                throw new InvalidArgumentException(sprintf(
+                    'Header value must be scalar but %s provided for header "%s".',
+                    is_object($value) ? get_class($value) : gettype($value),
+                    $header
+                ));
+            }
+        }
+    }
+
+    /**
+     * Decodes a valid json string into an array to send in Api calls.
+     *
+     * @param  mixed  $json         Must be null or array or a valid string json to be translated into a php array.
+     * @param  string $name         Name of the argument whose value is being validated in $json parameter.
+     * @param  bool   $associative  Should check for associative? Default: true.
+     *
+     * @return array|null    Returns an array made up of key-value pairs in the provided json string
+     *                       or throws exception, if the provided json is not valid.
+     * @throws InvalidArgumentException
+     */
+    public static function decodeJson($json, string $name, bool $associative = true): ?array
+    {
+        if (is_null($json) || (is_array($json) && (!$associative || CoreHelper::isAssociative($json)))) {
+            return $json;
+        }
+        if ($json instanceof stdClass) {
+            $json = json_encode($json);
+        }
+        if (is_string($json)) {
+            $decoded = json_decode($json, true);
+            if (is_array($decoded) && (!$associative || CoreHelper::isAssociative($decoded))) {
+                return $decoded;
+            }
+        }
+        throw new InvalidArgumentException("Invalid json value for argument: '$name'");
+    }
+
+    /**
+     * Decodes a valid jsonArray string into an array to send in Api calls.
+     *
+     * @param  mixed  $json   Must be null or array or a valid string jsonArray to be translated into a php array.
+     * @param  string $name   Name of the argument whose value is being validated in $json parameter.
+     * @param  bool   $asMap  Should decode as map? Default: false.
+     *
+     * @return array|null    Returns an array made up of key-value pairs in the provided jsonArray string
+     *                       or throws exception, if the provided json is not valid.
+     * @throws InvalidArgumentException
+     */
+    public static function decodeJsonArray($json, string $name, bool $asMap = false): ?array
+    {
+        $decoded = self::decodeJson($json, $name, false);
+        if (is_null($decoded)) {
+            return null;
+        }
+        $isAssociative = CoreHelper::isAssociative($decoded);
+        if (($asMap && $isAssociative) || (!$asMap && !$isAssociative)) {
+            return array_map(function ($v) use ($name) {
+                return self::decodeJson($v, $name);
+            }, $decoded);
+        }
+        $type = $asMap ? 'map' : 'array';
+        throw new InvalidArgumentException("Invalid json $type value for argument: '$name'");
+    }
+}

src/Legacy/Apis/ApplePayApi.php

@@ -0,0 +1,51 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Square\Legacy\Apis;
+
+use Core\Request\Parameters\BodyParam;
+use Core\Request\Parameters\HeaderParam;
+use CoreInterfaces\Core\Request\RequestMethod;
+use Square\Legacy\Http\ApiResponse;
+use Square\Legacy\Models\RegisterDomainRequest;
+use Square\Legacy\Models\RegisterDomainResponse;
+
+class ApplePayApi extends BaseApi
+{
+    /**
+     * Activates a domain for use with Apple Pay on the Web and Square. A validation
+     * is performed on this domain by Apple to ensure that it is properly set up as
+     * an Apple Pay enabled domain.
+     *
+     * This endpoint provides an easy way for platform developers to bulk activate
+     * Apple Pay on the Web with Square for merchants using their platform.
+     *
+     * Note: You will need to host a valid domain verification file on your domain to support Apple Pay.
+     * The
+     * current version of this file is always available at https://app.squareup.com/digital-wallets/apple-
+     * pay/apple-developer-merchantid-domain-association,
+     * and should be hosted at `.well_known/apple-developer-merchantid-domain-association` on your
+     * domain.  This file is subject to change; we strongly recommend checking for updates regularly and
+     * avoiding
+     * long-lived caches that might not keep in sync with the correct file version.
+     *
+     * To learn more about the Web Payments SDK and how to add Apple Pay, see [Take an Apple Pay
+     * Payment](https://developer.squareup.com/docs/web-payments/apple-pay).
+     *
+     * @param RegisterDomainRequest $body An object containing the fields to POST for the request.
+     *        See the corresponding object definition for field details.
+     *
+     * @return ApiResponse Response from the API call
+     */
+    public function registerDomain(RegisterDomainRequest $body): ApiResponse
+    {
+        $_reqBuilder = $this->requestBuilder(RequestMethod::POST, '/v2/apple-pay/domains')
+            ->auth('global')
+            ->parameters(HeaderParam::init('Content-Type', 'application/json'), BodyParam::init($body));
+
+        $_resHandler = $this->responseHandler()->type(RegisterDomainResponse::class)->returnApiResponse();
+
+        return $this->execute($_reqBuilder, $_resHandler);
+    }
+}

src/Legacy/Apis/BankAccountsApi.php

@@ -0,0 +1,93 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Square\Legacy\Apis;
+
+use Core\Request\Parameters\QueryParam;
+use Core\Request\Parameters\TemplateParam;
+use CoreInterfaces\Core\Request\RequestMethod;
+use Square\Legacy\Http\ApiResponse;
+use Square\Legacy\Models\GetBankAccountByV1IdResponse;
+use Square\Legacy\Models\GetBankAccountResponse;
+use Square\Legacy\Models\ListBankAccountsResponse;
+
+class BankAccountsApi extends BaseApi
+{
+    /**
+     * Returns a list of [BankAccount]($m/BankAccount) objects linked to a Square account.
+     *
+     * @param string|null $cursor The pagination cursor returned by a previous call to this
+     *        endpoint.
+     *        Use it in the next `ListBankAccounts` request to retrieve the next set
+     *        of results.
+     *
+     *        See the [Pagination](https://developer.squareup.com/docs/working-with-
+     *        apis/pagination) guide for more information.
+     * @param int|null $limit Upper limit on the number of bank accounts to return in the response.
+     *        Currently, 1000 is the largest supported limit. You can specify a limit
+     *        of up to 1000 bank accounts. This is also the default limit.
+     * @param string|null $locationId Location ID. You can specify this optional filter to retrieve
+     *        only the linked bank accounts belonging to a specific location.
+     *
+     * @return ApiResponse Response from the API call
+     */
+    public function listBankAccounts(
+        ?string $cursor = null,
+        ?int $limit = null,
+        ?string $locationId = null
+    ): ApiResponse {
+        $_reqBuilder = $this->requestBuilder(RequestMethod::GET, '/v2/bank-accounts')
+            ->auth('global')
+            ->parameters(
+                QueryParam::init('cursor', $cursor),
+                QueryParam::init('limit', $limit),
+                QueryParam::init('location_id', $locationId)
+            );
+
+        $_resHandler = $this->responseHandler()->type(ListBankAccountsResponse::class)->returnApiResponse();
+
+        return $this->execute($_reqBuilder, $_resHandler);
+    }
+
+    /**
+     * Returns details of a [BankAccount]($m/BankAccount) identified by V1 bank account ID.
+     *
+     * @param string $v1BankAccountId Connect V1 ID of the desired `BankAccount`. For more
+     *        information, see
+     *        [Retrieve a bank account by using an ID issued by V1 Bank Accounts API](https:
+     *        //developer.squareup.com/docs/bank-accounts-api#retrieve-a-bank-account-by-using-an-
+     *        id-issued-by-v1-bank-accounts-api).
+     *
+     * @return ApiResponse Response from the API call
+     */
+    public function getBankAccountByV1Id(string $v1BankAccountId): ApiResponse
+    {
+        $_reqBuilder = $this->requestBuilder(RequestMethod::GET, '/v2/bank-accounts/by-v1-id/{v1_bank_account_id}')
+            ->auth('global')
+            ->parameters(TemplateParam::init('v1_bank_account_id', $v1BankAccountId));
+
+        $_resHandler = $this->responseHandler()->type(GetBankAccountByV1IdResponse::class)->returnApiResponse();
+
+        return $this->execute($_reqBuilder, $_resHandler);
+    }
+
+    /**
+     * Returns details of a [BankAccount]($m/BankAccount)
+     * linked to a Square account.
+     *
+     * @param string $bankAccountId Square-issued ID of the desired `BankAccount`.
+     *
+     * @return ApiResponse Response from the API call
+     */
+    public function getBankAccount(string $bankAccountId): ApiResponse
+    {
+        $_reqBuilder = $this->requestBuilder(RequestMethod::GET, '/v2/bank-accounts/{bank_account_id}')
+            ->auth('global')
+            ->parameters(TemplateParam::init('bank_account_id', $bankAccountId));
+
+        $_resHandler = $this->responseHandler()->type(GetBankAccountResponse::class)->returnApiResponse();
+
+        return $this->execute($_reqBuilder, $_resHandler);
+    }
+}

src/Legacy/Apis/BaseApi.php

@@ -0,0 +1,46 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Square\Legacy\Apis;
+
+use Core\ApiCall;
+use Core\Client;
+use Core\Request\RequestBuilder;
+use Core\Response\ResponseHandler;
+
+/**
+ * Base controller
+ */
+class BaseApi
+{
+    /**
+     * Client instance
+     *
+     * @var Client
+     */
+    private $client;
+
+    public function __construct(Client $client)
+    {
+        $this->client = $client;
+    }
+
+    protected function execute(RequestBuilder $requestBuilder, ?ResponseHandler $responseHandler = null)
+    {
+        return (new ApiCall($this->client))
+            ->requestBuilder($requestBuilder)
+            ->responseHandler($responseHandler ?? $this->responseHandler())
+            ->execute();
+    }
+
+    protected function requestBuilder(string $requestMethod, string $path): RequestBuilder
+    {
+        return new RequestBuilder($requestMethod, $path);
+    }
+
+    protected function responseHandler(): ResponseHandler
+    {
+        return $this->client->getGlobalResponseHandler();
+    }
+}