Add metadata to responses

src/AmznSPAHttp.php

@@ -10,7 +10,10 @@
 use Illuminate\Http\Client\PendingRequest;
 use Illuminate\Http\Client\Request;
 use Illuminate\Http\Client\RequestException;
+use Illuminate\Http\Client\Response;
 use Illuminate\Support\Arr;
+use Jasara\AmznSPA\Constants\JasaraNotes;
+use Jasara\AmznSPA\DataTransferObjects\Schemas\MetadataSchema;
 use Psr\Http\Message\RequestInterface;
 
 class AmznSPAHttp
@@ -95,11 +98,15 @@ private function call(string $method, string $url, array $data = [], bool $grant
                 'response_data' => $response->json(),
             ]);
 
-            return array_keys_to_snake($response->json() ?: []);
+            return array_merge(array_keys_to_snake($response->json() ?: []), [
+                'metadata' => $this->getMetaData($response),
+            ]);
         } catch (RequestException $e) {
             try {
                 if ($this->shouldReturnErrorResponse($e)) {
-                    return array_keys_to_snake($e->response->json());
+                    return array_merge(array_keys_to_snake($e->response->json()), [
+                        'metadata' => $this->getMetadata($e->response),
+                    ]);
                 }
 
                 $this->handleRequestException($e, $grantless);
@@ -276,4 +283,18 @@ private function transformArraysToStrings(array $data): array
 
         return $data;
     }
+
+    private function getMetadata(Response $response): MetadataSchema
+    {
+        $data = $response->json();
+        $headers = $response->headers();
+
+        $jasara_notes = JasaraNotes::findNote(Arr::get($data, 'errors.0.message', ''));
+        $amzn_request_id = Arr::get($headers, 'x-amzn-RequestId.0');
+
+        return new MetadataSchema(
+            jasara_notes: $jasara_notes,
+            amzn_request_id:  $amzn_request_id,
+        );
+    }
 }

src/Constants/JasaraNotes.php

@@ -0,0 +1,24 @@
+<?php
+
+namespace Jasara\AmznSPA\Constants;
+
+/**
+ * A list of developer notes related to unusual or confusing errors.
+ */
+class JasaraNotes
+{
+    const NOTES_MAP = [
+        'The application isn\'t configured with roles.' => 'Your developer application listing on Seller Central has been approved but not published yet. It takes up to 10 days for an application to fully publish after approval. This applies to listing revisions as well. See this Github issue for more details: https://github.com/amzn/selling-partner-api-docs/issues/347#issuecomment-855153228',
+    ];
+
+    public static function findNote(string $error_message): string | null
+    {
+        $error_message = json_decode('"' . $error_message . '"'); // Decode Unicode
+
+        if (array_key_exists($error_message, self::NOTES_MAP)) {
+            return self::NOTES_MAP[$error_message];
+        }
+
+        return null;
+    }
+}

src/DataTransferObjects/Responses/BaseResponse.php

@@ -4,6 +4,7 @@
 
 use Jasara\AmznSPA\DataTransferObjects\Schemas\ErrorListSchema;
 use Jasara\AmznSPA\DataTransferObjects\Schemas\ErrorSchema;
+use Jasara\AmznSPA\DataTransferObjects\Schemas\MetadataSchema;
 use Spatie\DataTransferObject\Attributes\CastWith;
 use Spatie\DataTransferObject\Casters\ArrayCaster;
 use Spatie\DataTransferObject\DataTransferObject;
@@ -12,4 +13,6 @@ class BaseResponse extends DataTransferObject
 {
     #[CastWith(ArrayCaster::class, itemType: ErrorSchema::class)]
     public ?ErrorListSchema $errors;
+
+    public ?MetadataSchema $metadata;
 }

src/DataTransferObjects/Schemas/MetadataSchema.php

@@ -0,0 +1,14 @@
+<?php
+
+namespace Jasara\AmznSPA\DataTransferObjects\Schemas;
+
+use Spatie\DataTransferObject\DataTransferObject;
+
+class MetadataSchema extends DataTransferObject
+{
+    // Developer notes to provide additional context for unusual or
+    // confusing error messages
+    public ?string $jasara_notes;
+
+    public ?string $amzn_request_id;
+}

tests/Setup/SetupAmznSPAConfig.php

@@ -61,7 +61,9 @@ public function fakeHttpStub(string $stub, int $status_code = 200): Factory
     {
         $http = new Factory(new HttpEventHandler);
         $http->fake([
-            '*' => $http->response($this->loadHttpStub($stub), $status_code),
+            '*' => $http->response($this->loadHttpStub($stub), $status_code, [
+                'x-amzn-RequestId' => Str::random(),
+            ]),
         ]);
 
         return $http;

tests/Unit/AmznSPAHttpTest.php

@@ -11,6 +11,7 @@
 use Jasara\AmznSPA\DataTransferObjects\AuthTokensDTO;
 use Jasara\AmznSPA\DataTransferObjects\GrantlessTokenDTO;
 use Jasara\AmznSPA\DataTransferObjects\Responses\FulfillmentInbound\CreateInboundShipmentPlanResponse;
+use Jasara\AmznSPA\DataTransferObjects\Responses\FulfillmentInbound\GetAuthorizationCodeResponse;
 use Jasara\AmznSPA\DataTransferObjects\Schemas\Notifications\DestinationResourceSpecificationSchema;
 use Jasara\AmznSPA\HttpEventHandler;
 use Jasara\AmznSPA\Tests\Unit\UnitTestCase;
@@ -199,6 +200,25 @@ public function testInvalidResponseNotReturned()
         $amzn->fulfillment_inbound->createInboundShipmentPlan($this->setupInboundShipmentPlanRequest());
     }
 
+    public function testMetadata()
+    {
+        list($config, $http) = $this->setupConfigWithFakeHttp('errors/application-no-roles');
+
+        $seller_id = Str::random();
+        $developer_id = Str::random();
+        $mws_auth_token = Str::random();
+
+        $amzn = new AmznSPA($config);
+        $amzn = $amzn->usingMarketplace('ATVPDKIKX0DER');
+        $response = $amzn->authorization->getAuthorizationCodeFromMwsToken($seller_id, $developer_id, $mws_auth_token);
+
+        $this->assertInstanceOf(GetAuthorizationCodeResponse::class, $response);
+        $this->assertNotNull($response->metadata);
+        $this->assertNotNull($response->metadata->amzn_request_id);
+        $this->assertNotNull($response->metadata->jasara_notes);
+        $this->assertStringContainsString('approved but not published yet', $response->metadata->jasara_notes);
+    }
+
     /**
      * @group external
      * An actual API call is required here, in order to test the request signing and test endpoints.

tests/Unit/Constants/JasaraNotesTest.php

@@ -0,0 +1,36 @@
+<?php
+
+namespace Jasara\AmznSPA\Unit\Constants;
+
+use Illuminate\Support\Str;
+use Jasara\AmznSPA\Constants\JasaraNotes;
+use Jasara\AmznSPA\Tests\Unit\UnitTestCase;
+
+/**
+ * @covers \Jasara\AmznSPA\Constants\JasaraNotes
+ */
+class JasaraNotesTest extends UnitTestCase
+{
+    public function testGetNote()
+    {
+        $error = 'The application isn\u0027t configured with roles.';
+        $result = JasaraNotes::findNote($error);
+
+        $this->assertIsString($result);
+        $this->assertStringContainsString('approved but not published', $result);
+
+        $error = 'The application isn\'t configured with roles.';
+        $result = JasaraNotes::findNote($error);
+
+        $this->assertIsString($result);
+        $this->assertStringContainsString('approved but not published', $result);
+    }
+
+    public function testGetNull()
+    {
+        $error = Str::random();
+        $result = JasaraNotes::findNote($error);
+
+        $this->assertNull($result);
+    }
+}

tests/stubs/errors/application-no-roles.json

@@ -0,0 +1,9 @@
+{
+    "errors": [
+        {
+            "code": "InvalidInput",
+            "message": "The application isn\\u0027t configured with roles.",
+            "details": ""
+        }
+    ]
+}