2.0.0

API/Client.php

@@ -0,0 +1,79 @@
+<?php
+namespace Dfe\Square\API;
+use Dfe\Square\Settings as S;
+use Zend_Http_Client as C;
+// 2017-10-08
+final class Client extends \Df\API\Client {
+	/**
+	 * 2017-10-08
+	 * «For `POST` and `PUT` requests, you instead provide parameters as JSON in the body of your request.»
+	 * «Connect API v2 Reference» → «Connect API v2 Conventions» → «Providing parameters» →
+	 * «POST and PUT requests»
+	 * https://docs.connect.squareup.com/api/connect/v2#postandputrequests
+	 * @override
+	 * @see \Df\API\Client::_construct()
+	 * @used-by \Df\API\Client::__construct()
+	 */
+	protected function _construct() {
+		parent::_construct();
+		/**
+		 * 2017-10-08
+		 * «For `POST` and `PUT` requests, you instead provide parameters as JSON in the body of your request.»
+		 * «Connect API v2 Reference» → «Connect API v2 Conventions» → «Providing parameters» →
+		 * «POST and PUT requests»
+		 * https://docs.connect.squareup.com/api/connect/v2#postandputrequests
+		 */
+		$this->reqJson();
+		/**
+		 * 2017-10-08
+		 * «By default, all endpoint responses provide data as JSON in the response body
+		 * and include a `Content-Type: application/json header`.»
+		 * «Connect API v2 Reference» → «Connect API v2 Conventions» → «Request and response headers»
+		 * https://docs.connect.squareup.com/api/connect/v2#requestandresponseheaders
+		 */
+		$this->resJson();
+		/**
+		 * 2017-10-08
+		 * A response's root tag is just a syntax sugar.
+		 * Look at the `GET /v2/locations` response, for example: https://mage2.pro/t/4647
+	 	 *		{"locations": [{<...>}, {<...>}, {<...>}]}
+		 */
+		$this->resStripRoot();
+	}
+
+
+	/**
+	 * 2017-10-08
+	 * «Connect API v2 Reference» → «Connect API v2 Conventions» → «Request and response headers»
+	 * «`POST` and `PUT` requests must include one additional header: `Content-Type: application/json`»
+	 * https://docs.connect.squareup.com/api/connect/v2#requestandresponseheaders
+	 * @override
+	 * @see \Df\API\Client::headers()
+	 * @used-by \Df\API\Client::__construct()
+	 * @used-by \Df\API\Client::p()
+	 * @return array(string => string)
+	 */
+	protected function headers() {/** @var S $s */$s = dfps($this); return
+		['Accept' => 'application/json', 'Authorization' => "Bearer {$s->accessToken()}"]
+		+ (!in_array($this->method(), [C::POST, C::PUT]) ? [] : ['Content-Type' => 'application/json'])
+	;}
+
+	/**
+	 * 2017-10-08
+	 * @see \Df\API\Client::responseValidatorC()
+	 * @used-by \Df\API\Client::p()
+	 * @return string
+	 */
+	protected function responseValidatorC() {return \Dfe\Square\API\Validator::class;}
+
+	/**
+	 * 2017-10-08 «Connect API v2 Reference» → «Connect API v2 Conventions» → «Endpoint paths»
+	 * https://docs.connect.squareup.com/api/connect/v2#endpointpaths
+	 * @override
+	 * @see \Df\API\Client::uriBase()
+	 * @used-by \Df\API\Client::__construct()
+	 * @used-by \Df\API\Client::_p()
+	 * @return string
+	 */
+	protected function uriBase() {return 'https://connect.squareup.com/v2';}
+}

API/Facade/Card.php

@@ -0,0 +1,31 @@
+<?php
+namespace Dfe\Square\API\Facade;
+/**
+ * 2017-10-08
+ * «Connect API v2 Reference» → «Endpoints» → «Customers» → «CreateCustomerCard»
+ * https://docs.connect.squareup.com/api/connect/v2#endpoint-createcustomercard
+ */
+final class Card extends \Df\API\Facade {
+	/**
+	 * 2017-10-08
+	 * @param string $customerId
+	 */
+	function __construct($customerId) {$this->_customerId = $customerId;}
+
+	/**
+	 * 2017-10-08
+	 * @override
+	 * @see \Df\API\Facade::prefix()
+	 * @used-by \Df\API\Facade::p()
+	 * @return string
+	 */
+	protected function prefix() {return "customers/{$this->_customerId}";}
+
+	/**
+	 * 2017-10-08
+	 * @used-by __construct()
+	 * @used-by prefix()
+	 * @var string
+	 */
+	private $_customerId;
+}

API/Facade/Customer.php

@@ -0,0 +1,9 @@
+<?php
+namespace Dfe\Square\API\Facade;
+/**
+ * 2017-10-08
+ * Note 1. «Connect API v2 Reference» → «Endpoints» → «Customers»
+ * https://docs.connect.squareup.com/api/connect/v2#navsection-customers
+ * Note 2. [Square] An example of a response to `POST /v2/customers`: https://mage2.pro/t/4649
+ */
+final class Customer extends \Df\API\Facade {}

API/Facade/Location.php

@@ -0,0 +1,46 @@
+<?php
+namespace Dfe\Square\API\Facade;
+/**
+ * 2017-10-08
+ * Note 1. «Connect API v2 Reference» → «Endpoints» → «Locations»
+ * https://docs.connect.squareup.com/api/connect/v2#navsection-locations
+ * Note 2. «Connect API v2 Reference» → «Data Types» → «Location»
+ * https://docs.connect.squareup.com/api/connect/v2#type-location
+ * Note 3. [Square] An example of a response to `GET /v2/locations`: https://mage2.pro/t/4647
+ */
+final class Location extends \Df\API\Facade {
+	/**
+	 * 2017-10-08 E.g.: ['CBASEC-iHv7Pl3-MI-zj3uIgNm8' => 'Coffee & Toffee NYC']
+	 * @used-by \Dfe\Square\Source\Location::fetch()
+	 * @return array(string => string)
+	 */
+	function map() {return df_sort(array_column(
+		array_filter($this->all()->a(), function(array $i) {return
+			/**
+			 * 2017-10-08
+			 * Note 1.
+			 * «Connect API v2 Reference» → «Data Types» → «Location»
+			 * «The location's status. See `LocationStatus` for possible values.»
+			 * https://docs.connect.squareup.com/api/connect/v2#type-location
+			 * Note 2.
+			 * «Connect API v2 Reference» → «Enums» → «LocationStatus»
+			 * https://docs.connect.squareup.com/api/connect/v2#type-locationstatus
+			 *
+			 * `ACTIVE`
+			 * 		A fully operational location.
+			 * 		The location can be used across all Square products and APIs.
+			 *
+			 * `INACTIVE`
+			 * 		A functionally limited location.
+			 * 		The location can only be used via Square APIs.
+			 *
+			 * NOTE:
+			 * We strongly discourage the use of inactive locations.
+			 * Making API calls with inactive locations will cause complications
+			 * if the restrictions on inactive locations increase in the future.
+			 */
+			'ACTIVE' === $i['status']
+		;})
+		,'name', 'id'
+	));}
+}

API/Facade/LocationBased.php

@@ -0,0 +1,18 @@
+<?php
+namespace Dfe\Square\API\Facade;
+use Dfe\Square\Settings as S;
+/**
+ * 2017-10-08
+ * «Connect API v2 Reference» → «Connect API v2 Conventions» → «Endpoint paths»
+ * https://docs.connect.squareup.com/api/connect/v2#endpointpaths
+ */
+abstract class LocationBased extends \Df\API\Facade {
+	/**
+	 * 2017-10-08
+	 * @override
+	 * @see \Df\API\Facade::prefix()
+	 * @used-by \Df\API\Facade::p()
+	 * @return string
+	 */
+	protected function prefix() {/** @var S $s */$s = dfps($this); return "locations/{$s->location()}";}
+}

API/Facade/Transaction.php

@@ -0,0 +1,40 @@
+<?php
+namespace Dfe\Square\API\Facade;
+use Df\API\Operation as O;
+use Zend_Http_Client as Z;
+/**
+ * 2017-10-08
+ * Note 1. «Connect API v2 Reference» → «Endpoints» → «Transactions»
+ * https://docs.connect.squareup.com/api/connect/v2#navsection-transactions
+ * Note 2. [Square] An example of a response to `POST /v2/locations/{location_id}/transactions`
+ * https://mage2.pro/t/4648
+ */
+final class Transaction extends LocationBased {
+	/**
+	 * 2017-10-09 «Connect API v2 Reference» → «Endpoints» → «Transactions» → «CaptureTransaction»
+	 * https://docs.connect.squareup.com/api/connect/v2#endpoint-capturetransaction
+	 * @used-by \Dfe\Square\Facade\Charge::capturePreauthorized()
+	 * @param string $id
+	 * @return O
+	 */
+	function capture($id) {return $this->p($id, Z::POST, 'capture');}
+
+	/**
+	 * 2017-10-09 «Connect API v2 Reference» → «Endpoints» → «Transactions» → «VoidTransaction»
+	 * https://docs.connect.squareup.com/api/connect/v2#endpoint-voidtransaction
+	 * @used-by \Dfe\Square\Facade\Charge::void()
+	 * @param string $id
+	 * @return O
+	 */
+	function void_($id) {return $this->p($id, Z::POST, 'void');}
+
+	/**
+	 * 2017-10-09 «Connect API v2 Reference» → «Endpoints» → «Transactions» → «CreateRefund»
+	 * https://docs.connect.squareup.com/api/connect/v2#endpoint-createrefund
+	 * @used-by \Dfe\Square\Facade\Charge::refund()
+	 * @param string $id
+	 * @param array(string => mixed) $p
+	 * @return O
+	 */
+	function refund($id, array $p) {return $this->p([$id, $p], Z::POST, 'refund');}
+}

API/Validator.php

@@ -0,0 +1,72 @@
+<?php
+namespace Dfe\Square\API;
+/**
+ * 2017-10-08
+ * «Connect API v2 Reference» → «Connect API v2 Conventions» → «Handling errors»
+ * https://docs.connect.squareup.com/api/connect/v2#handlingerrors
+ * @used-by \Dfe\Square\API\Client::responseValidatorC()
+ * @used-by \Dfe\Square\Source\Location::exception()
+ */
+final class Validator extends \Df\API\Response\Validator {
+	/**
+	 * 2017-10-08
+	 * @override
+	 * @see \Df\API\Exception::long()
+	 * @used-by \Df\API\Client::p()
+	 * @return string
+	 */
+	function long() {return df_json_encode($this->errors());}
+
+	/**
+	 * 2017-10-08
+	 * @override
+	 * @see \Df\API\Exception::short()
+	 * @used-by \Df\API\Client::p()
+	 * @used-by \Dfe\Square\Source\Location::exception()
+	 * @return string
+	 */
+	function short() {return df_cc_br(array_column($this->errors(), 'detail'));}
+
+	/**
+	 * 2017-10-08
+	 * @override
+	 * @see \Df\API\Response\Validator::valid()
+	 * @used-by \Df\API\Response\Validator::validate()
+	 * @return bool
+	 */
+	function valid() {return !$this->errors();}
+
+	/**
+	 * 2017-10-08
+	 * All Connect v2 endpoints include an errors array in their response body
+	 * if any errors occurred during a request. The response body has the following structure:
+	 *	{
+	 *		"errors": [
+	 *			{
+	 *				"category": "AUTHENTICATION_ERROR"
+	 *				,"code": "UNAUTHORIZED"
+	 *				,"detail": "This request could not be authorized."
+	 *			}
+	 *		]
+	 *	}
+	 * Each error in the array has the following fields:
+	 * `category`:
+	 * 		indicates which high-level category the error falls into.
+	 * 		This value never changes for a particular error.
+	 * 		See `ErrorCategory` for possible values:
+	 * 		https://docs.connect.squareup.com/api/connect/v2#type-errorcategory
+	 * `code`:
+	 * 		indicates the exact type of error that occurred.
+	 * 		This value never changes for a particular error.
+	 * 		See `ErrorCode` for possible values:
+	 * 		https://docs.connect.squareup.com/api/connect/v2#type-errorcode
+	 * `detail`:
+	 * 		is a human-readable string that will help you diagnose the error.
+	 * 		This value can change for a particular error.
+	 * @used-by long()
+	 * @used-by short()
+	 * @used-by valid()
+	 * @return array(array(string => string))|null
+	 */
+	private function errors() {return dfa($this->r(), 'errors');}
+}

Block/Info.php

@@ -2,14 +2,22 @@
 namespace Dfe\Square\Block;
 // 2016-10-06
 /** @final Unable to use the PHP «final» keyword here because of the M2 code generation. */
-class Info extends \Df\Payment\Block\Info {
+class Info extends \Df\StripeClone\Block\Info {
 	/**
 	 * 2016-10-06
 	 * @override
-	 * @see \Df\Payment\Block\Info::prepare()
+	 * @see \Df\StripeClone\Block\Info::prepare()
 	 * @used-by \Df\Payment\Block\Info::_prepareSpecificInformation()
 	 */
-	final protected function prepare() {$i = $this->ii(); $this->si(
-		'Card', df_cc_s($i->getCcType(), '****' . $i->getCcLast4())
-	);}
+	final protected function prepare() {
+		if ($this->tm()->res0()) {
+			parent::prepare();
+		}
+		else {
+			// 2017-10-10 This branch is for legacy transactions
+			// (before the `Df_StripeClone` module usage).
+			$i = $this->ii();
+			$this->si('Card', df_cc_s($i->getCcType(), '****' . $i->getCcLast4()));
+		}
+	}
 }