Now casting eagerly loaded Threads to their appropriate types

examples/conversations.php

@@ -20,7 +20,7 @@
 
 // GET conversation with the threads
 $conversationRequest = new ConversationRequest();
-$conversationRequest->withThreads();
+$conversationRequest = $conversationRequest->withThreads();
 $conversation = $client->conversations()->get(12, $conversationRequest);
 
 // List conversations

src/Conversations/Conversation.php

@@ -771,6 +771,11 @@ public function addCustomField(CustomField $customField): Conversation
     /**
      * Obtain the threads that were eagerly loaded when this conversation was obtained.
      *
+     * We will attempt to map the incoming Thread to a typed class.  The only threads
+     * we type are threads that can be created through the API (e.g. CustomerThread,
+     * NoteThread, etc.).  We do not type any kind of system threads such as a notice
+     * that a Workflow has run on a Conversation.
+     *
      * @see ConversationRequest
      *
      * @return Thread[]|Collection

src/Conversations/ConversationLoader.php

@@ -4,7 +4,7 @@
 
 namespace HelpScout\Api\Conversations;
 
-use HelpScout\Api\Conversations\Threads\Thread;
+use HelpScout\Api\Conversations\Threads\ThreadFactory;
 use HelpScout\Api\Customers\Customer;
 use HelpScout\Api\Entity\LinkedEntityLoader;
 use HelpScout\Api\Mailboxes\Mailbox;
@@ -43,7 +43,11 @@ public function load()
         }
 
         if ($this->shouldLoadResource(ConversationLinks::THREADS)) {
-            $threads = $this->loadResources(Thread::class, ConversationLinks::THREADS);
+            $threadFactory = new ThreadFactory();
+            $threads = $this->loadResources(function (array $data) use ($threadFactory) {
+                return $threadFactory->make($data['type'], $data);
+            }, ConversationLinks::THREADS);
+
             $conversation->setThreads($threads);
         }
 

src/Conversations/Threads/ThreadFactory.php

@@ -15,6 +15,11 @@ class ThreadFactory
         '_default' => Thread::class,
     ];
 
+    /**
+     * Attempt to map the incoming Thread to a typed class.  The only threads we type
+     * are threads that can be created through the API.  We do not type any kind of
+     * system threads such as a notice that a Workflow has run on a Conversation.
+     */
     public function make(string $type, array $data): Thread
     {
         /** @var Thread $thread */

src/Entity/LinkedEntityLoader.php

@@ -48,6 +48,8 @@ protected function shouldLoadResource(string $rel): bool
      * @param string $rel
      *
      * @return mixed
+     * @throws \HelpScout\Api\Exception\JsonException
+     * @throws \GuzzleHttp\Exception\GuzzleException
      */
     protected function loadResource(string $entityClass, string $rel)
     {
@@ -57,12 +59,14 @@ protected function loadResource(string $entityClass, string $rel)
     }
 
     /**
-     * @param string $entityClass
+     * @param \Closure|string $entityClass
      * @param string $rel
      *
      * @return Collection
+     * @throws \HelpScout\Api\Exception\JsonException
+     * @throws \GuzzleHttp\Exception\GuzzleException
      */
-    protected function loadResources(string $entityClass, string $rel): Collection
+    protected function loadResources($entityClass, string $rel): Collection
     {
         $uri = $this->resource->getLinks()->getHref($rel);
         $resources = $this->restClient->getResources($entityClass, $rel, $uri);

src/Http/RestClient.php

@@ -72,9 +72,10 @@ public function getDefaultHeaders(): array
 
     /**
      * @param Extractable $entity
-     * @param string      $uri
+     * @param string $uri
      *
      * @return int|null
+     * @throws \GuzzleHttp\Exception\GuzzleException
      */
     public function createResource(Extractable $entity, string $uri): ?int
     {
@@ -94,7 +95,8 @@ public function createResource(Extractable $entity, string $uri): ?int
 
     /**
      * @param Extractable $entity
-     * @param string      $uri
+     * @param string $uri
+     * @throws \GuzzleHttp\Exception\GuzzleException
      */
     public function updateResource(Extractable $entity, string $uri): void
     {
@@ -109,7 +111,8 @@ public function updateResource(Extractable $entity, string $uri): void
 
     /**
      * @param Extractable $entity
-     * @param string      $uri
+     * @param string $uri
+     * @throws \GuzzleHttp\Exception\GuzzleException
      */
     public function patchResource(Extractable $entity, string $uri): void
     {
@@ -124,6 +127,7 @@ public function patchResource(Extractable $entity, string $uri): void
 
     /**
      * @param string $uri
+     * @throws \GuzzleHttp\Exception\GuzzleException
      */
     public function deleteResource(string $uri): void
     {
@@ -137,9 +141,11 @@ public function deleteResource(string $uri): void
 
     /**
      * @param \Closure|string $entityClass
-     * @param string          $uri
+     * @param string $uri
      *
      * @return HalResource
+     * @throws \HelpScout\Api\Exception\JsonException
+     * @throws \GuzzleHttp\Exception\GuzzleException
      */
     public function getResource($entityClass, string $uri): HalResource
     {
@@ -158,6 +164,8 @@ public function getResource($entityClass, string $uri): HalResource
      * @param Report $report
      *
      * @return array
+     * @throws \GuzzleHttp\Exception\GuzzleException
+     * @throws \HelpScout\Api\Exception\JsonException
      */
     public function getReport(Report $report): array
     {
@@ -175,10 +183,12 @@ public function getReport(Report $report): array
 
     /**
      * @param \Closure|string $entityClass
-     * @param string          $rel
-     * @param string          $uri
+     * @param string $rel
+     * @param string $uri
      *
      * @return HalResources
+     * @throws \GuzzleHttp\Exception\GuzzleException
+     * @throws \HelpScout\Api\Exception\JsonException
      */
     public function getResources($entityClass, string $rel, string $uri): HalResources
     {
@@ -207,6 +217,7 @@ private function encodeEntity(Extractable $entity): string
      * @param Request $request
      *
      * @return mixed|ResponseInterface
+     * @throws \GuzzleHttp\Exception\GuzzleException
      */
     private function send(Request $request)
     {

tests/Conversations/ConversationIntegrationTest.php

@@ -9,7 +9,7 @@
 use HelpScout\Api\Conversations\ConversationRequest;
 use HelpScout\Api\Conversations\CustomField;
 use HelpScout\Api\Conversations\CustomFieldsCollection;
-use HelpScout\Api\Conversations\Threads\Thread;
+use HelpScout\Api\Conversations\Threads\CustomerThread;
 use HelpScout\Api\Customers\Customer;
 use HelpScout\Api\Entity\Collection;
 use HelpScout\Api\Mailboxes\Mailbox;
@@ -221,7 +221,8 @@ public function testGetConversationPreloadsThreads()
         $threads = $conversation->getThreads();
 
         $this->assertInstanceOf(Collection::class, $threads);
-        $this->assertInstanceOf(Thread::class, $threads[0]);
+
+        $this->assertInstanceOf(CustomerThread::class, $threads[0]);
 
         $this->verifyMultipleRequests([
             ['GET', 'https://api.helpscout.net/v2/conversations/1'],