docs: Add migration guides for v2 to v3 and v3 to v4

README.md

@@ -508,24 +508,6 @@ try {
 A response that is not shaped like a Seam error, such as a gateway returning
 HTML, raises the underlying Guzzle exception instead.
 
-## Upgrading from 3.x
-
-- PHP 8.2 or later is required. PHP 8.1 reached end of life in December 2025.
-- The client class is `Seam\Seam`, replacing `Seam\SeamClient`.
-- The constructor takes named options, so `$endpoint` is no longer the second
-  positional argument, and `$throw_http_errors` is gone: an API error always
-  raises.
-- The exception classes stay in the `Seam\` namespace and now share a
-  `Seam\SeamException` interface.
-- `$seam->action_attempts->poll_until_ready()` is gone. Use
-  `wait_for_action_attempt`, which also takes a `timeout` and
-  `polling_interval`.
-- `$seam->client` is the Guzzle client, and `$seam->api_key` and the global
-  `LTS_VERSION` constant are gone. Use `Seam\Seam::LTS_VERSION`.
-- A response in the 3xx range is no longer treated as successful.
-- Requests time out after 30 seconds and are retried twice.
-- Pagination metadata is a `Seam\Pagination` rather than a `stdClass`.
-
 ## Development and Testing
 
 ### Quickstart

codegen/layouts/seam-client.hbs

@@ -27,11 +27,6 @@ class Seam
   public {{clientName}}Client ${{namespace}};
 {{/each}}
 
-  /**
-   * The long term support version of the Seam API this SDK targets.
-   */
-  public const LTS_VERSION = ClientFactory::LTS_VERSION;
-
   /**
    * The Guzzle client this instance makes its requests with.
    *

src/Http/ClientFactory.php

@@ -11,8 +11,6 @@
  */
 final class ClientFactory
 {
-    public const LTS_VERSION = "1.0.0";
-
     /**
      * How many times a failed request is retried unless the caller says
      * otherwise.
@@ -93,10 +91,8 @@ private static function sdk_headers(): array
         $version = Version::get();
 
         return [
-            "User-Agent" => "seam-php/" . $version,
             "seam-sdk-name" => "seamapi/php",
             "seam-sdk-version" => $version,
-            "seam-lts-version" => self::LTS_VERSION,
         ];
     }
 }

src/Options.php

@@ -18,8 +18,7 @@ public static function get_endpoint(?string $endpoint = null): string
 
     public static function get_endpoint_from_env(): ?string
     {
-        $seam_endpoint = self::get_env("SEAM_ENDPOINT");
-        return $seam_endpoint
+        return self::get_env("SEAM_ENDPOINT");
     }
 
     public static function is_seam_options_with_api_key(

src/SeamWithoutWorkspace.php

@@ -18,8 +18,6 @@
  */
 class SeamWithoutWorkspace
 {
-    public const LTS_VERSION = ClientFactory::LTS_VERSION;
-
     /**
      * The Guzzle client this instance makes its requests with.
      */

tests/ClientTest.php

@@ -240,9 +240,4 @@ public function testWaitForActionAttemptDefaultCanBeDisabled(): void
 
         $this->assertFalse($seam->defaults["wait_for_action_attempt"]);
     }
-
-    public function testLtsVersionIsExposed(): void
-    {
-        $this->assertSame("1.0.0", Seam::LTS_VERSION);
-    }
 }

tests/HeadersTest.php

@@ -5,7 +5,6 @@
 namespace Tests;
 
 use PHPUnit\Framework\TestCase;
-use Seam\Http\ClientFactory;
 use Seam\Seam;
 use Seam\Version;
 use Tests\Support\RecordingClient;
@@ -52,13 +51,31 @@ public function testSendsDefaultHeaders(): void
             Version::get(),
             $request->getHeaderLine("seam-sdk-version"),
         );
-        $this->assertSame(
-            ClientFactory::LTS_VERSION,
-            $request->getHeaderLine("seam-lts-version"),
+        $this->assertStringStartsWith(
+            "GuzzleHttp/",
+            $request->getHeaderLine("User-Agent"),
         );
+    }
+
+    public function testSendsTheCallerUserAgentUnchanged(): void
+    {
+        $recorder = new RecordingClient([
+            RecordingClient::json(200, ["device" => ["device_id" => "d1"]]),
+        ]);
+
+        $seam = Seam::from_api_key(
+            "seam_apikey_token",
+            endpoint: "https://example.com",
+            guzzle_options: array_merge($recorder->guzzle_options(), [
+                "headers" => ["User-Agent" => "acme-app/1.0"],
+            ]),
+        );
+
+        $seam->devices->get("d1");
+
         $this->assertSame(
-            "seam-php/" . Version::get(),
-            $request->getHeaderLine("User-Agent"),
+            "acme-app/1.0",
+            $recorder->request()->getHeaderLine("User-Agent"),
         );
     }