From ce717e95bdc81d283e8ba6321eaa9757b7c17349 Mon Sep 17 00:00:00 2001
From: Vitaliy Sunny <3903438+sunnyphp@users.noreply.github.com>
Date: Tue, 28 Nov 2023 08:22:24 +0300
Subject: [PATCH] Readme init, small fixes

---
 readme.md                                     | 68 +++++++++++++++++++
 .../{EkeyException.php => KeyException.php}   |  2 +-
 src/Middleware.php                            |  2 +-
 3 files changed, 70 insertions(+), 2 deletions(-)
 create mode 100644 readme.md
 rename src/Exception/{EkeyException.php => KeyException.php} (93%)

diff --git a/readme.md b/readme.md
new file mode 100644
index 0000000..2024966
--- /dev/null
+++ b/readme.md
@@ -0,0 +1,68 @@
+# TTLock Cloud API SDK
+
+PHP SDK for [TTLock Cloud API v3](https://euopen.ttlock.com/document/doc?urlName=cloud/oauth2/getAccessTokenEn.html)
+
+## Installation
+
+See [clients & adapters](https://docs.php-http.org/en/latest/clients.html) list in HTTPlug documentation
+if you're using another HTTP client (not Guzzle 7).
+
+HTTP client should be compatible with PSR-18 (implementing `psr/http-client-implementation`).
+
+```shell
+composer require sunnyphp/ttlock php-http/guzzle7-adapter
+```
+
+```php
+require_once __DIR__ . '/vendor/autoload.php';
+
+use SunnyPHP\TTLock\Configuration;
+use SunnyPHP\TTLock\Entrypoint;
+use SunnyPHP\TTLock\Request\Lock\Initialize;
+use SunnyPHP\TTLock\Request\OAuth2\AccessToken;
+use SunnyPHP\TTLock\Request\User\Register;
+use SunnyPHP\TTLock\Transport;
+
+// initial configuration
+$entrypoint = new Entrypoint(
+	new Configuration('client_id', 'client_secret', /* access token if needed */),
+	new Transport(\Http\Adapter\Guzzle7\Client::createWithConfig([
+		'verify' => false,	// disable certificates check
+	])),
+);
+
+// register user; retrieve TTLock Cloud API username
+$register = $entrypoint->getUserRegister(new Register('username', 'password'));
+var_dump($register->getResponseArray());
+
+// get access token; retrieve access token, refresh token, expiration, etc
+$tokenResponse = $entrypoint->getOAuth2AccessToken(new AccessToken($register->getUsername(), 'password'));
+var_dump($tokenResponse->getResponseArray());
+
+// save token response to future requests or refreshing token
+// ...
+
+// inject access token to entrypoint configuration (most of the requests required access token)
+$entrypoint = $entrypoint->withConfigurationAccessToken($tokenResponse->getAccessToken());
+
+// initialize new lock; access token used under hood; retrieve lockId, keyId
+$lockData = 'TTLock SDK should return lockData here';
+$newLockIds = $entrypoint->getLockInitialize(new Initialize($lockData));
+var_dump($newLockIds->getResponseArray());
+
+// get all initialized locks
+$locks = $entrypoint->getLockList();
+var_dump($locks->getResponseArray());
+
+// other requests
+```
+
+## Exception structure
+
+- `\SunnyPHP\TTLock\Exception\ApiException` - communication or system errors
+	- `\SunnyPHP\TTLock\Exception\CommonException` - if response has errors
+    - `\SunnyPHP\TTLock\Exception\KeyException` - if response has `Ekey`-associated errors
+    - `\SunnyPHP\TTLock\Exception\GatewayException` - if response has `Gateway`-associated errors
+    - `\SunnyPHP\TTLock\Exception\LockException` - if response has `Lock`-associated errors
+    - `\SunnyPHP\TTLock\Exception\PasscodeException` - if response has `Passcode` or `IC`-associated errors
+- `\Webmozart\Assert\InvalidArgumentException` - if passed data is invalid
diff --git a/src/Exception/EkeyException.php b/src/Exception/KeyException.php
similarity index 93%
rename from src/Exception/EkeyException.php
rename to src/Exception/KeyException.php
index 46fee4c..4bdf6eb 100644
--- a/src/Exception/EkeyException.php
+++ b/src/Exception/KeyException.php
@@ -7,7 +7,7 @@
  * Ekey related errors
  * @link https://euopen.ttlock.com/document/doc?urlName=cloud/errorCodeEn.html
  */
-final class EkeyException extends ApiException
+final class KeyException extends ApiException
 {
 	protected static array $codeToMessageList = [
 		-1008 => 'eKey does not exist',
diff --git a/src/Middleware.php b/src/Middleware.php
index c83cfd4..ce66889 100644
--- a/src/Middleware.php
+++ b/src/Middleware.php
@@ -6,7 +6,7 @@
 use SunnyPHP\TTLock\Contract\Middleware\MiddlewareInterface;
 use Webmozart\Assert\Assert;
 
-class Middleware
+final class Middleware
 {
 	/**
 	 * @var MiddlewareInterface[][]