Merge pull request #12 from smartsendio/develop

v0.2.0
smartsendio · Jun 15, 2020 · 3e10a42 · 3e10a42
2 parents c8778ee + 7ee57d5
commit 3e10a42
Show file tree

Hide file tree

Showing 47 changed files with 1,370 additions and 804 deletions.
diff --git a/LICENSE b/LICENSE
diff --git a/README.md b/README.md
@@ -7,6 +7,8 @@
 
 PHP SDK for interacting with the Smart Send API.
 
+Check our [Swagger documentation](https://app.swaggerhub.com/apis/smartsendio/webshop/) for more details.
+
 ## Install
 
 Via Composer
@@ -26,41 +28,49 @@ require __DIR__.'/../vendor/autoload.php';
 And finally create an instance of the SDK:
 
 ```php
-$client = new Smartsendio\Api\Adapters\GuzzleClientAdapter(new \GuzzleHttp\Client()); // Any client implementing ClientInterface
-$api = new Smartsendio\Api\ApiFactory($client);
+$client = new Smartsendio\Api\Adapters\GuzzleClientAdapter(new \GuzzleHttp\Client());
+$api = new Smartsendio\Api\ApiFactory($client); // Any client that implements ClientInterface can be used
 $api->apiToken('API_TOKEN_HERE')->website('WEBSITE'); // Set the authentication parameters
 ```
 
 ### Demo mode
 Demo mode can be used for testing and is activated like so:
 
 ```php
-$api->demo(); // Not the api is in demo mode.
+$api->demo(); // Api is now in demo mode.
 ```
 
 ### Fetching agents
-Agents are fetched using the `agent` API.
+Agents are fetched using the `agents` API.
 
 ```php
 // Example: All agents for a given carrier in a zipcode
-$response = $api->agents()
+$response = $api->agents() // AgentApiInterface
     ->carrier('postnord')
     ->country('DK')
     ->zipcode('2100')
-    ->get(); // ApiResponseInterface
+    ->get(); // PaginatedAgentApiResponseInterface
 
 // Example: The closest agents for a given carrier based on a given address
-$response = $api->agents()
+$response = $api->agents() // AgentApiInterface
     ->carrier('postnord')
     ->country('DK')
     ->zipcode('2100')
     ->street('Nordre Frihavnsgade 1')
-    ->closest(); // ApiResponseInterface
+    ->closest(); // PaginatedAgentApiResponseInterface
+
+// Example: Get a single agent using the carries own unique agent number
+$response = $api->agents() // AgentApiInterface
+    ->carrier('postnord')
+    ->country('DK')
+    ->lookup('1234567'); // AgentApiResponseInterface
 ```
 
 ### Shipments
+Booking of shipments (creating shipping labels) are done by firstly creating the complex `Shipment` object and passing that to the `shipments` API:
+
 ```php
-$item = new \Smartsendio\Api\Data\Item([
+$item = \Smartsendio\Api\Data\Item::make([
    'internal_id' => '000000123',
    'internal_reference' => 'PRODUCT-1231456',
    'sku' => '012345678',
@@ -78,7 +88,7 @@ $item = new \Smartsendio\Api\Data\Item([
    'total_tax_amount' => 20.3,
 ]);
 
-$parcel = new \Smartsendio\Api\Data\Parcel([
+$parcel = \Smartsendio\Api\Data\Parcel::make([
     'internal_id' => '00100025556',
     'internal_reference' => 'ABC12345678',
     'weight' => 9.3,
@@ -109,16 +119,21 @@ $shipment->setReceiver([
     'email' => 'email@example.com',
 ])->addParcel($parcel);
 
-$api->book($shipment); // ApiResponseInterface
+$response = $api->booking()  // BookingApiInterface
+    ->shipment($shipment); // BookingApiResponseInterface
 ```
 
 ### Dealing with errors
 This is how to deal with API errors:
 
 ```php
-$api->shipments()->book($shipment); // ApiResponseInterface
-$api->isSuccessful(); // false
-$api->getError(); // ApiErrorInterface
+$response = $api->booking()->shipment($shipment); // ApiResponseInterface
+$response->isSuccessful(); // false
+$error = $response->getError(); // ApiErrorInterface
+$error->getId(); // Unique id of the error
+$error->getCode(); // Error code describing the type of error
+$error->getMessage(); // Description of the error
+$error->getErrors(); // Return each individual error
 ```
 
 ## Change log

diff --git a/src/AbstractApiResponse.php b/src/AbstractApiResponse.php
@@ -0,0 +1,63 @@
+<?php
+
+namespace Smartsendio\Api;
+
+use Psr\Http\Message\ResponseInterface as Psr7ResponseInterface;
+use Smartsendio\Api\Contracts\ApiErrorInterface;
+use Smartsendio\Api\Contracts\ApiResponseInterface;
+
+abstract class AbstractApiResponse implements ApiResponseInterface
+{
+    /** @var ApiResponseInterface */
+    protected $api_response;
+
+    public function __construct(ApiResponseInterface $api_response)
+    {
+        $this->api_response = $api_response;
+    }
+
+    public function getDecodedData(): array
+    {
+        return $this->api_response->getDecodedData();
+    }
+
+    public function isSuccessful(): bool
+    {
+        return $this->api_response->isSuccessful();
+    }
+
+    public function getResponse(): Psr7ResponseInterface
+    {
+        return $this->api_response->getResponse();
+    }
+
+    public function hasData(): bool
+    {
+        return $this->api_response->hasData();
+    }
+
+    public function hasLinks(): bool
+    {
+        return $this->api_response->hasData();
+    }
+
+    public function getLinks(): array
+    {
+        return $this->api_response->getLinks();
+    }
+
+    public function hasMeta(): bool
+    {
+        return $this->api_response->hasMeta();
+    }
+
+    public function getMeta(): array
+    {
+        return $this->api_response->getMeta();
+    }
+
+    public function getError(): ApiErrorInterface
+    {
+        return $this->api_response->getError();
+    }
+}
diff --git a/src/AgentApi.php b/src/AgentApi.php
@@ -4,6 +4,7 @@
 
 use InvalidArgumentException;
 use Smartsendio\Api\Contracts\AgentApiInterface;
+use Smartsendio\Api\Contracts\AgentApiResponseInterface;
 use Smartsendio\Api\Contracts\ClientInterface;
 use Smartsendio\Api\Contracts\ApiResponseInterface;
 use Smartsendio\Api\Traits\PaginatableTrait;
@@ -58,7 +59,7 @@ public function street(string $street): AgentApiInterface
         return $this;
     }
 
-    public function lookup(string $agentNo): ApiResponseInterface
+    public function lookup(string $agentNo): AgentApiResponseInterface
     {
         $this->checkRequiredAuthenticationParameters();
 
@@ -76,24 +77,28 @@ public function lookup(string $agentNo): ApiResponseInterface
             'agentno' => $agentNo,
         ];
 
-        return $this->client->get(
+        $apiResponse = $this->client->get(
             $this->getBaseUri($this->api_endpoint_base).$this->getPathString($pathParameters),
             [
                 'api_token' => $this->token,
             ]
         );
+
+        return new AgentApiResponse($apiResponse);
     }
 
-    public function find(string $id): ApiResponseInterface
+    public function find(string $id): AgentApiResponseInterface
     {
         $this->checkRequiredAuthenticationParameters();
 
-        return $this->client->get(
+        $apiResponse = $this->client->get(
             $this->getBaseUri($this->api_endpoint_base).$id.'/',
             [
                 'api_token' => $this->token,
             ]
         );
+
+        return new AgentApiResponse($apiResponse);
     }
 
     public function get(): ApiResponseInterface
@@ -115,12 +120,14 @@ public function get(): ApiResponseInterface
             'street' => $this->street,
         ]);
 
-        return $this->client->get(
+        $apiResponse = $this->client->get(
             $this->getBaseUri($this->api_endpoint_base).$this->getPathString($pathParameters),
             [
                 'api_token' => $this->token,
             ]
         );
+
+        return new PaginatedAgentApiResponse($apiResponse);
     }
 
     public function closest(): ApiResponseInterface
@@ -142,12 +149,14 @@ public function closest(): ApiResponseInterface
             'street' => $this->street,
         ]);
 
-        return $this->client->get(
+        $apiResponse = $this->client->get(
             $this->getBaseUri($this->api_endpoint_base).'closest/'.$this->getPathString($pathParameters),
             [
                 'api_token' => $this->token,
             ]
         );
+
+        return new PaginatedAgentApiResponse($apiResponse);
     }
 
     /** @throws InvalidArgumentException */

diff --git a/src/AgentApiResponse.php b/src/AgentApiResponse.php
@@ -0,0 +1,21 @@
+<?php
+
+namespace Smartsendio\Api;
+
+use Smartsendio\Api\Contracts\AgentApiResponseInterface;
+use Smartsendio\Api\Data\Responses\AgentResponse;
+
+class AgentApiResponse extends AbstractApiResponse implements AgentApiResponseInterface
+{
+    /** @var AgentResponse */
+    protected $data;
+
+    public function getData(): AgentResponse
+    {
+        if (empty($this->data)) {
+            $this->data = new AgentResponse($this->api_response->getDecodedData());
+        }
+
+        return $this->data;
+    }
+}
diff --git a/src/ApiError.php b/src/ApiError.php
@@ -2,12 +2,13 @@
 
 namespace Smartsendio\Api;
 
+use Smartsendio\Api\Contracts\ApiErrorInterface;
 use Smartsendio\Api\Contracts\ApiErrorLinksInterface;
-use Smartsendio\Api\Traits\ArrayConstructableTrait;
+use Smartsendio\Api\Traits\ArrayMakableTrait;
 
-class ApiError implements Contracts\ApiErrorInterface
+class ApiError implements ApiErrorInterface
 {
-    use ArrayConstructableTrait;
+    use ArrayMakableTrait;
 
     /** @ApiErrorLinksInterface */
     public $links;
@@ -44,29 +45,31 @@ public function getMessage(): string
         return $this->message;
     }
 
-    /**
-     * @inheritDoc
-     */
     public function getErrors(): array
     {
         return $this->errors;
     }
 
     private function setLinks(array $links): void
     {
-        $this->links = new ApiErrorLinks($links);
+        $this->links = ApiErrorLinks::make($links);
     }
 
     private function setCode(string $code): void
     {
         $this->code = $code;
     }
 
-    private function setId(string $message): void
+    private function setMessage(string $message): void
     {
         $this->message = $message;
     }
 
+    private function setId(string $id): void
+    {
+        $this->id = $id;
+    }
+
     private function setErrors(array $errors): void
     {
         $this->errors = $errors;

diff --git a/src/ApiErrorLinks.php b/src/ApiErrorLinks.php
@@ -2,11 +2,11 @@
 
 namespace Smartsendio\Api;
 
-use Smartsendio\Api\Traits\ArrayConstructableTrait;
+use Smartsendio\Api\Traits\ArrayMakableTrait;
 
 class ApiErrorLinks implements Contracts\ApiErrorLinksInterface
 {
-    use ArrayConstructableTrait;
+    use ArrayMakableTrait;
 
     /** @string */
     public $about;

diff --git a/src/ApiFactory.php b/src/ApiFactory.php
@@ -4,8 +4,8 @@
 
 use Smartsendio\Api\Contracts\AgentApiInterface;
 use Smartsendio\Api\Contracts\ApiFactoryInterface;
+use Smartsendio\Api\Contracts\BookingApiInterface;
 use Smartsendio\Api\Contracts\ClientInterface;
-use Smartsendio\Api\Contracts\ShipmentsApiInterface;
 use Smartsendio\Api\Traits\ApiAuthenticationTrait;
 
 class ApiFactory implements ApiFactoryInterface
@@ -35,9 +35,9 @@ public function agents(array $parameters = []): AgentApiInterface
         return $api;
     }
 
-    public function shipments(array $parameters = []): ShipmentsApiInterface
+    public function bookings(array $parameters = []): BookingApiInterface
     {
-        $api = new ShipmentApi($this->client);
+        $api = new BookingApi($this->client);
 
         if ($this->token) {
             $api->token($this->token);