From e67901078adff38e7620b3cd06c16b84310e1566 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Joachim=20L=C3=B8vgaard?= <joachim@loevgaard.dk>
Date: Wed, 17 Jun 2026 09:26:28 +0200
Subject: [PATCH] Add readable endpoint to fetch a resource by ID

Introduce ReadableEndpointInterface and ReadableEndpointTrait providing getById() (GET /{endpoint}/{id}), and wire it into the sales orders endpoint. Also add Client::setDebug() to target the sandbox API host.
---
 src/Client/Client.php                         | 12 ++++++-
 src/Client/Endpoint/Endpoint.php              |  1 -
 .../Endpoint/ReadableEndpointInterface.php    | 18 +++++++++++
 src/Client/Endpoint/ReadableEndpointTrait.php | 31 +++++++++++++++++++
 src/Client/Endpoint/SalesOrdersEndpoint.php   |  5 +++
 .../Endpoint/SalesOrdersEndpointInterface.php |  3 +-
 src/Response/Collection.php                   |  1 -
 7 files changed, 67 insertions(+), 4 deletions(-)
 create mode 100644 src/Client/Endpoint/ReadableEndpointInterface.php
 create mode 100644 src/Client/Endpoint/ReadableEndpointTrait.php

diff --git a/src/Client/Client.php b/src/Client/Client.php
index 0177a14..5c00c2d 100644
--- a/src/Client/Client.php
+++ b/src/Client/Client.php
@@ -57,6 +57,8 @@ final class Client implements ClientInterface, LoggerAwareInterface
 
     private ?MapperBuilder $mapperBuilder = null;
 
+    private bool $debug = false;
+
     public function __construct(private readonly string $username, private readonly string $apiKey)
     {
         $this->logger = new NullLogger();
@@ -212,9 +214,17 @@ public function setLogger(LoggerInterface $logger): void
         $this->logger = $logger;
     }
 
+    public function setDebug(bool $debug): void
+    {
+        $this->debug = $debug;
+    }
+
     private function getBaseUri(): string
     {
-        return 'https://app.shipmondo.com/api/public/v3';
+        return sprintf(
+            'https://%s.shipmondo.com/api/public/v3',
+            $this->debug ? 'sandbox' : 'app',
+        );
     }
 
     private function getHttpClient(): HttpClientInterface
diff --git a/src/Client/Endpoint/Endpoint.php b/src/Client/Endpoint/Endpoint.php
index 8dbfb12..cfa31f0 100644
--- a/src/Client/Endpoint/Endpoint.php
+++ b/src/Client/Endpoint/Endpoint.php
@@ -19,7 +19,6 @@
 
 /**
  * @template TResponse of Response
- *
  * @implements EndpointInterface<TResponse>
  */
 abstract class Endpoint implements EndpointInterface, LoggerAwareInterface
diff --git a/src/Client/Endpoint/ReadableEndpointInterface.php b/src/Client/Endpoint/ReadableEndpointInterface.php
new file mode 100644
index 0000000..af93926
--- /dev/null
+++ b/src/Client/Endpoint/ReadableEndpointInterface.php
@@ -0,0 +1,18 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Setono\Shipmondo\Client\Endpoint;
+
+use Setono\Shipmondo\Response\Response;
+
+/**
+ * @template TResponse of Response
+ */
+interface ReadableEndpointInterface
+{
+    /**
+     * @return TResponse
+     */
+    public function getById(int $id): Response;
+}
diff --git a/src/Client/Endpoint/ReadableEndpointTrait.php b/src/Client/Endpoint/ReadableEndpointTrait.php
new file mode 100644
index 0000000..92244a7
--- /dev/null
+++ b/src/Client/Endpoint/ReadableEndpointTrait.php
@@ -0,0 +1,31 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Setono\Shipmondo\Client\Endpoint;
+
+use Setono\Shipmondo\Response\Response;
+
+/**
+ * @mixin Endpoint
+ *
+ * @template TResponse of Response
+ */
+trait ReadableEndpointTrait
+{
+    /**
+     * @return TResponse
+     */
+    public function getById(int $id): Response
+    {
+        return $this
+            ->mapperBuilder
+            ->mapper()
+            ->map(
+                self::getResponseClass(),
+                $this->createSource(
+                    $this->client->get(sprintf('%s/%d', $this->endpoint, $id)),
+                ),
+            );
+    }
+}
diff --git a/src/Client/Endpoint/SalesOrdersEndpoint.php b/src/Client/Endpoint/SalesOrdersEndpoint.php
index 0852727..7e1b157 100644
--- a/src/Client/Endpoint/SalesOrdersEndpoint.php
+++ b/src/Client/Endpoint/SalesOrdersEndpoint.php
@@ -16,6 +16,11 @@ final class SalesOrdersEndpoint extends Endpoint implements SalesOrdersEndpointI
      */
     use CreatableEndpointTrait;
 
+    /**
+     * @use ReadableEndpointTrait<SalesOrderResponse>
+     */
+    use ReadableEndpointTrait;
+
     protected static function getResponseClass(): string
     {
         return SalesOrderResponse::class;
diff --git a/src/Client/Endpoint/SalesOrdersEndpointInterface.php b/src/Client/Endpoint/SalesOrdersEndpointInterface.php
index 30e8e5e..c0d5300 100644
--- a/src/Client/Endpoint/SalesOrdersEndpointInterface.php
+++ b/src/Client/Endpoint/SalesOrdersEndpointInterface.php
@@ -9,7 +9,8 @@
 /**
  * @extends EndpointInterface<SalesOrderResponse>
  * @extends CreatableEndpointInterface<SalesOrderResponse>
+ * @extends ReadableEndpointInterface<SalesOrderResponse>
  */
-interface SalesOrdersEndpointInterface extends EndpointInterface, CreatableEndpointInterface
+interface SalesOrdersEndpointInterface extends EndpointInterface, CreatableEndpointInterface, ReadableEndpointInterface
 {
 }
diff --git a/src/Response/Collection.php b/src/Response/Collection.php
index ca17ae2..bfdedc5 100644
--- a/src/Response/Collection.php
+++ b/src/Response/Collection.php
@@ -6,7 +6,6 @@
 
 /**
  * @template T
- *
  * @implements \IteratorAggregate<int, T>
  */
 final class Collection implements \Countable, \IteratorAggregate