feat(MT-4270): An option to return raw response (#13)

* feat(MT-4270): An option to return raw response * chore(MT-4270): address comments * chore(MT-4270): fix all psalm errors * fix(MT-4270): exception should not throw when keeping response * chore(MT-4270): address more comments
LiveIntent · Jun 2, 2023 · 1084cce · 1084cce
1 parent a9fd235
commit 1084cce
Show file tree

Hide file tree

Showing 17 changed files with 175 additions and 68 deletions.
diff --git a/src/Client/AbstractClient.php b/src/Client/AbstractClient.php
@@ -135,4 +135,9 @@ public function __get($name)
 
         return $this->serviceFactory->make($name, $this->options);
     }
+
+    public function getOptions(): array
+    {
+        return $this->options;
+    }
 }
diff --git a/src/LiveIntentClient.php b/src/LiveIntentClient.php
@@ -7,12 +7,16 @@
 /**
  * Client used to interact with the LiveIntent Api.
  *
+ * @property \LiveIntent\Services\AdSlotService $adSlots
  * @property \LiveIntent\Services\AdvertiserService $advertisers
  * @property \LiveIntent\Services\AuthService $auth
  * @property \LiveIntent\Services\CampaignService $campaigns
  * @property \LiveIntent\Services\InsertionOrderService $insertionOrders
  * @property \LiveIntent\Services\LineItemService $lineItems
+ * @property \LiveIntent\Services\MediaGroupService $mediaGroups
  * @property \LiveIntent\Services\NewsletterService $newsletters
+ * @property \LiveIntent\Services\PublisherService $publishers
+ * @property \LiveIntent\Services\UserService $users
  *
  * @property \LiveIntent\Services\BaseService $request
  */

diff --git a/src/ResourceResponse.php b/src/ResourceResponse.php
@@ -0,0 +1,17 @@
+<?php
+
+namespace LiveIntent;
+
+use Illuminate\Http\Client\Response;
+
+class ResourceResponse
+{
+    public Resource|null $resource;
+    public Response $response;
+
+    public function __construct(Resource|null $resource, Response $rawResponse)
+    {
+        $this->resource = $resource;
+        $this->response = $rawResponse;
+    }
+}
diff --git a/src/ResourceServiceOptions.php b/src/ResourceServiceOptions.php
@@ -0,0 +1,13 @@
+<?php
+
+namespace LiveIntent;
+
+class ResourceServiceOptions
+{
+    public bool $keepRawResponse;
+
+    public function withRawResponse(): void
+    {
+        $this->keepRawResponse = true;
+    }
+}
diff --git a/src/Services/AbstractResourceService.php b/src/Services/AbstractResourceService.php
@@ -4,6 +4,8 @@
 
 use LiveIntent\Resource;
 use LiveIntent\Exceptions;
+use LiveIntent\ResourceResponse;
+use LiveIntent\ResourceServiceOptions;
 use Illuminate\Support\Traits\ForwardsCalls;
 
 abstract class AbstractResourceService extends BaseService
@@ -28,37 +30,40 @@ abstract class AbstractResourceService extends BaseService
      * Find a resource by its id.
      *
      * @param string|int $id
-     * @return \LiveIntent\Resource
+     * @param ResourceServiceOptions $options
+     * @return \LiveIntent\Resource|ResourceResponse
      */
-    public function find($id)
+    public function find($id, ResourceServiceOptions $options = null)
     {
-        return $this->request('get', $this->resourceUrl($id));
+        return $this->requestWithOptions('get', $this->resourceUrl($id), $options);
     }
 
     /**
      * Create a new resource.
      *
      * @param array|\stdClass|\LiveIntent\Resource $attributes
-     * @return \LiveIntent\Resource
+     * @param ResourceServiceOptions $options
+     * @return \LiveIntent\Resource|ResourceResponse
      */
-    public function create($attributes)
+    public function create($attributes, ResourceServiceOptions $options = null)
     {
         $payload = (array) $attributes;
 
         if ($attributes instanceof Resource) {
             $payload = $attributes->getAttributes();
         }
 
-        return $this->withJson($payload)->request('post', $this->baseUrl);
+        return $this->withJson($payload)->requestWithOptions('post', $this->baseUrl, $options);
     }
 
     /**
      * Update an existing resource.
      *
      * @param array|\stdClass|\LiveIntent\Resource $attributes
-     * @return \LiveIntent\Resource
+     * @param ResourceServiceOptions $options
+     * @return \LiveIntent\Resource|ResourceResponse
      */
-    public function update($attributes)
+    public function update($attributes, ResourceServiceOptions $options = null)
     {
         $payload = (array) $attributes;
         $id = $payload['id'] ?? null;
@@ -72,16 +77,17 @@ public function update($attributes)
             throw Exceptions\InvalidArgumentException::factory($payload, 'Unable to find `id` for update operation');
         }
 
-        return $this->withJson($payload)->request('post', $this->resourceUrl($id));
+        return $this->withJson($payload)->requestWithOptions('post', $this->resourceUrl($id), $options);
     }
 
     /**
      * Update an existing resource.
      *
      * @param array|\stdClass|\LiveIntent\Resource $attributes
-     * @return \LiveIntent\Resource
+     * @param ResourceServiceOptions $options
+     * @return \LiveIntent\Resource|ResourceResponse
      */
-    public function createOrUpdate($attributes)
+    public function createOrUpdate($attributes, ResourceServiceOptions $options = null)
     {
         $payload = (array) $attributes;
         $id = $payload['id'] ?? null;
@@ -92,45 +98,36 @@ public function createOrUpdate($attributes)
         }
 
         if ($id && empty($attributes['version'])) {
-            $payload['version'] = $this->find($id)->version;
+            $resource = $this->find($id);
+            if ($resource instanceof Resource) {
+                $payload['version'] = $resource->version;
+            }
         }
 
-        return $this->withJson($payload)->request('post', $id ? $this->resourceUrl($id) : $this->baseUrl);
+        return $this->withJson($payload)->requestWithOptions('post', $id ? $this->resourceUrl($id) : $this->baseUrl, $options);
     }
 
-    // /**
-    //  */
-    // public function createMany($attributeGroups)
-    // {
-    //     //
-    // }
-
-    // /**
-    //  */
-    // public function updateMany($attributeGroups)
-    // {
-    //     //
-    // }
-
     /**
      * Delete a resource by its id.
      *
      * @param string|int $arg
-     * @return \LiveIntent\Resource
+     * @return \Illuminate\Http\Client\Response
      */
     public function delete($arg)
     {
         return $this->requestRaw('delete', $this->resourceUrl($arg));
     }
 
     /**
-     * Issue a raw request without mapping the respon.se
+     * Issue a raw request without mapping the response
+     *
+     * @param ResourceServiceOptions $options
      *
      * @return \Illuminate\Http\Client\Response
      */
-    public function requestRaw(string $method, string $url, array $options = [])
+    public function requestRaw(string $method, string $url, ResourceServiceOptions $options = null)
     {
-        return parent::request($method, $url, $options);
+        return parent::request($method, $url, [], $options);
     }
 
     /**
@@ -172,15 +169,23 @@ public function search(array $payload, array $options = [])
      *
      * @param string $method
      * @param string $url
-     * @param array $options
+     * @param ResourceServiceOptions $options
      *
-     * @return \LiveIntent\Resource
+     * @return \LiveIntent\Resource|ResourceResponse
      */
-    public function request(string $method, string $url, array $options = [])
+    public function requestWithOptions(string $method, string $url, ResourceServiceOptions $options = null)
     {
         $response = $this->requestRaw($method, $url, $options);
+        $json = $response->json();
+
+        $output = array_key_exists('output', $json) ? $json['output'] : [];
+        $resource = $this->newResource($output);
+
+        if ($options && $options->keepRawResponse) {
+            return new ResourceResponse($resource, $response);
+        }
 
-        return $this->newResource($response->json()['output']);
+        return $resource;
     }
 
     /**

diff --git a/src/Services/AdSlotService.php b/src/Services/AdSlotService.php
@@ -5,9 +5,9 @@
 use LiveIntent\AdSlot;
 
 /**
- * @method \LiveIntent\AdSlot find($id)
- * @method \LiveIntent\AdSlot create($attributes)
- * @method \LiveIntent\AdSlot update($attributes)
+ * @method \LiveIntent\AdSlot find($id, $options = null)
+ * @method \LiveIntent\AdSlot create($attributes, $options = null)
+ * @method \LiveIntent\AdSlot update($attributes, $options = null)
  */
 class AdSlotService extends AbstractResourceService
 {

diff --git a/src/Services/AdvertiserService.php b/src/Services/AdvertiserService.php
@@ -5,9 +5,9 @@
 use LiveIntent\Advertiser;
 
 /**
- * @method \LiveIntent\Advertiser find($id)
- * @method \LiveIntent\Advertiser create($attributes)
- * @method \LiveIntent\Advertiser update($attributes)
+ * @method \LiveIntent\Advertiser find($id, $options = null)
+ * @method \LiveIntent\Advertiser create($attributes, $options = null)
+ * @method \LiveIntent\Advertiser update($attributes, $options = null)
  */
 class AdvertiserService extends AbstractResourceService
 {

diff --git a/src/Services/BaseService.php b/src/Services/BaseService.php
@@ -3,6 +3,7 @@
 namespace LiveIntent\Services;
 
 use Illuminate\Http\Client\Factory;
+use LiveIntent\ResourceServiceOptions;
 use Illuminate\Http\Client\PendingRequest;
 use Illuminate\Support\Traits\ForwardsCalls;
 
@@ -84,17 +85,22 @@ public function actingAs(int $userId)
      * @param string $method
      * @param string $url
      * @param array $options
+     * @param ResourceServiceOptions $rsOptions
      * @return \Illuminate\Http\Client\Response
      */
-    public function request(string $method, string $url, array $options = [])
-    {
+    public function request(
+        string $method,
+        string $url,
+        array $options = [],
+        ResourceServiceOptions $rsOptions = null
+    ) {
         $request = tap($this->pendingRequest(), function ($request) {
             $this->authenticateRequest($request);
         });
 
         $response = $request->send($method, $url, $options);
 
-        $this->handleErrors($response);
+        $this->handleErrors($response, $rsOptions);
 
         return $response;
     }
@@ -103,7 +109,7 @@ public function request(string $method, string $url, array $options = [])
      * Attach a json body to the request.
      *
      * @param array $data
-     * @return PendingRequest
+     * @return BaseService
      */
     public function withJson(array $data)
     {

diff --git a/src/Services/CampaignService.php b/src/Services/CampaignService.php
@@ -5,9 +5,9 @@
 use LiveIntent\Campaign;
 
 /**
- * @method \LiveIntent\Campaign find($id)
- * @method \LiveIntent\Campaign create($attributes)
- * @method \LiveIntent\Campaign update($attributes)
+ * @method \LiveIntent\Campaign find($id, $options = null)
+ * @method \LiveIntent\Campaign create($attributes, $options = null)
+ * @method \LiveIntent\Campaign update($attributes, $options = null)
  */
 class CampaignService extends AbstractResourceService
 {

diff --git a/src/Services/Concerns/HandlesApiErrors.php b/src/Services/Concerns/HandlesApiErrors.php
@@ -4,19 +4,22 @@
 
 use LiveIntent\Exceptions;
 use Illuminate\Http\Client\Response;
+use LiveIntent\ResourceServiceOptions;
 
 trait HandlesApiErrors
 {
     /**
      * Check for api errors and handle them accordingly.
      *
+     * @param ResourceServiceOptions $rsOptions
+     *
      * @throws \LiveIntent\Exceptions\AbstractRequestException
      *
      * @return void
      */
-    private function handleErrors(Response $response)
+    private function handleErrors(Response $response, ResourceServiceOptions $options = null)
     {
-        if ($response->successful()) {
+        if ($response->successful() || ($options && $options->keepRawResponse)) {
             return;
         }
 

diff --git a/src/Services/InsertionOrderService.php b/src/Services/InsertionOrderService.php
@@ -5,9 +5,9 @@
 use LiveIntent\InsertionOrder;
 
 /**
- * @method \LiveIntent\InsertionOrder find($id)
- * @method \LiveIntent\InsertionOrder create($attributes)
- * @method \LiveIntent\InsertionOrder update($attributes)
+ * @method \LiveIntent\InsertionOrder find($id, $options = null)
+ * @method \LiveIntent\InsertionOrder create($attributes, $options = null)
+ * @method \LiveIntent\InsertionOrder update($attributes, $options = null)
  */
 class InsertionOrderService extends AbstractResourceService
 {

diff --git a/src/Services/LineItemService.php b/src/Services/LineItemService.php
@@ -5,9 +5,9 @@
 use LiveIntent\LineItem;
 
 /**
- * @method \LiveIntent\LineItem find($id)
- * @method \LiveIntent\LineItem create($attributes)
- * @method \LiveIntent\LineItem update($attributes)
+ * @method \LiveIntent\LineItem find($id, $options = null)
+ * @method \LiveIntent\LineItem create($attributes, $options = null)
+ * @method \LiveIntent\LineItem update($attributes, $options = null)
  */
 class LineItemService extends AbstractResourceService
 {

diff --git a/src/Services/MediaGroupService.php b/src/Services/MediaGroupService.php
@@ -5,9 +5,9 @@
 use LiveIntent\MediaGroup;
 
 /**
- * @method \LiveIntent\MediaGroup find($id)
- * @method \LiveIntent\MediaGroup create($attributes)
- * @method \LiveIntent\MediaGroup update($attributes)
+ * @method \LiveIntent\MediaGroup find($id, $options = null)
+ * @method \LiveIntent\MediaGroup create($attributes, $options = null)
+ * @method \LiveIntent\MediaGroup update($attributes, $options = null)
  */
 class MediaGroupService extends AbstractResourceService
 {

diff --git a/src/Services/NewsletterService.php b/src/Services/NewsletterService.php
@@ -5,9 +5,9 @@
 use LiveIntent\Newsletter;
 
 /**
- * @method \LiveIntent\Newsletter find($id)
- * @method \LiveIntent\Newsletter create($attributes)
- * @method \LiveIntent\Newsletter update($attributes)
+ * @method \LiveIntent\Newsletter find($id, $options = null)
+ * @method \LiveIntent\Newsletter create($attributes, $options = null)
+ * @method \LiveIntent\Newsletter update($attributes, $options = null)
  */
 class NewsletterService extends AbstractResourceService
 {

diff --git a/src/Services/PublisherService.php b/src/Services/PublisherService.php
@@ -5,9 +5,9 @@
 use LiveIntent\Publisher;
 
 /**
- * @method \LiveIntent\Publisher find($id)
- * @method \LiveIntent\Publisher create($attributes)
- * @method \LiveIntent\Publisher update($attributes)
+ * @method \LiveIntent\Publisher find($id, $options = null)
+ * @method \LiveIntent\Publisher create($attributes, $options = null)
+ * @method \LiveIntent\Publisher update($attributes, $options = null)
  */
 class PublisherService extends AbstractResourceService
 {