feat: add _strict=true to the URL search params serializer

Mirror seamapi/python#617: the new StrictUrlSearchParamsSerializer
wraps the base serializer and appends _strict=true to any non-empty
query, telling the Seam API to use strict, schema-aware parsing. The
flag is appended after the sort so it always sits last, a
caller-supplied _strict param is replaced rather than repeated, and a
query with no serializable params stays empty.

The flag is Seam API behavior, not part of the serialization standard,
so it is isolated in the wrapper and the base UrlSearchParamsSerializer
stays a pure implementation of the standard. The SDK client serializes
every request with the strict wrapper.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01HMKbYgbsoFdKiiaxXB6jh2

Author: claude

README.md

@@ -400,17 +400,22 @@ query strings with
 [`@seamapi/url-search-params-parser`](https://github.com/seamapi/url-search-params-parser).
 
 The serializer is exported for callers building requests with their own
-HTTP client:
+HTTP client. Use `StrictUrlSearchParamsSerializer` when calling the Seam
+API: it adds `_strict=true` to any non-empty query, which tells the API to
+use strict, schema-aware parsing, and is what the SDK's own requests use. A
+query with no serializable params remains empty.
+`UrlSearchParamsSerializer` is the same serialization without the flag — a
+pure implementation of the standard.
 
 ```php
-use Seam\UrlSearchParamsSerializer;
+use Seam\StrictUrlSearchParamsSerializer;
 
-$query = UrlSearchParamsSerializer::serialize([
+$query = StrictUrlSearchParamsSerializer::serialize([
     "device_ids" => ["device1", "device2"],
     "custom_metadata_has" => ["tag" => "front"],
     "limit" => 20,
 ]);
-// => 'custom_metadata_has.tag=front&device_ids=device1&device_ids=device2&limit=20'
+// => 'custom_metadata_has.tag=front&device_ids=device1&device_ids=device2&limit=20&_strict=true'
 ```
 
 A param that cannot be represented in the standard, such as `NAN` or a key

src/Http/SerializingClient.php

@@ -7,17 +7,18 @@
 use Psr\Http\Message\RequestInterface;
 use Psr\Http\Message\ResponseInterface;
 use Seam\NullValue;
-use Seam\UrlSearchParamsSerializer;
+use Seam\StrictUrlSearchParamsSerializer;
 
 /**
  * Applies the Seam serialization standard to every request the wrapped
  * client sends.
  *
- * Query params given as a map are serialized with UrlSearchParamsSerializer
- * and handed to Guzzle as a raw query string, because Guzzle's own encoder
- * follows different rules: it escapes `*`, leaves `~` alone, and drops an
- * empty array instead of sending `name=`. A query already given as a string
- * is a representation the caller chose, so it passes through untouched.
+ * Query params given as a map are serialized with
+ * StrictUrlSearchParamsSerializer and handed to Guzzle as a raw query
+ * string, because Guzzle's own encoder follows different rules: it escapes
+ * `*`, leaves `~` alone, and drops an empty array instead of sending
+ * `name=`. A query already given as a string is a representation the
+ * caller chose, so it passes through untouched.
  *
  * NullValue::NULL sentinels in a JSON body become JSON null, so the same
  * sentinel works whether a route sends a query string or a body.
@@ -96,7 +97,7 @@ private static function serialize_options(array $options): array
             ($options["query"] instanceof \stdClass ||
                 is_array($options["query"]))
         ) {
-            $serialized = UrlSearchParamsSerializer::serialize(
+            $serialized = StrictUrlSearchParamsSerializer::serialize(
                 $options["query"],
             );
 

src/StrictUrlSearchParamsSerializer.php

@@ -0,0 +1,54 @@
+<?php
+
+namespace Seam;
+
+/**
+ * Serializes params for the Seam API: the URL search params standard plus
+ * `_strict=true` appended to any non-empty query, which tells the API to
+ * use strict, schema-aware parsing. A query with no serializable params
+ * remains empty.
+ *
+ * The strict flag is Seam API behavior, not part of the serialization
+ * standard, so it lives here rather than in UrlSearchParamsSerializer,
+ * which stays a pure implementation of the standard.
+ */
+final class StrictUrlSearchParamsSerializer
+{
+    /**
+     * Serializes params to a URL search param query string with strict API
+     * validation enabled, without a leading `?`.
+     *
+     * @param array<string, mixed>|\stdClass $params
+     *
+     * @throws UnserializableParamError If any param could not be serialized
+     */
+    public static function serialize(array|\stdClass $params): string
+    {
+        $search_params = new UrlSearchParams();
+        self::update($search_params, $params);
+
+        return $search_params->to_string();
+    }
+
+    /**
+     * Updates existing URL search params with serialized params and strict
+     * API validation enabled.
+     *
+     * @param array<string, mixed>|\stdClass $params
+     *
+     * @throws UnserializableParamError If any param could not be serialized
+     */
+    public static function update(
+        UrlSearchParams $search_params,
+        array|\stdClass $params,
+    ): void {
+        UrlSearchParamsSerializer::update($search_params, $params);
+
+        if (count($search_params) > 0) {
+            // Replaced rather than repeated, and appended after the sort so
+            // it always sits last.
+            $search_params->delete("_strict");
+            $search_params->append("_strict", "true");
+        }
+    }
+}

tests/HeadersTest.php

@@ -35,7 +35,10 @@ public function testSendsDefaultHeaders(): void
         $request = $recorder->request();
 
         $this->assertSame("/devices/get", $request->getUri()->getPath());
-        $this->assertSame("device_id=d1", $request->getUri()->getQuery());
+        $this->assertSame(
+            "device_id=d1&_strict=true",
+            $request->getUri()->getQuery(),
+        );
 
         $this->assertSame(
             "Bearer seam_apikey_token",

tests/SearchParamsTest.php

@@ -47,7 +47,8 @@ public function testClientSerializesSearchParams(): void
                 "&custom_metadata_has.tag=front" .
                 "&device_ids=device1" .
                 "&device_ids=device2" .
-                "&limit=20",
+                "&limit=20" .
+                "&_strict=true",
             $recording->request()->getUri()->getQuery(),
         );
         $this->assertSame("GET", $recording->request()->getMethod());
@@ -74,7 +75,7 @@ public function testClientDoesNotReencodeTheSerializedSearchParams(): void
         ]);
 
         $this->assertSame(
-            "search=a+*%7E+b",
+            "search=a+*%7E+b&_strict=true",
             $recording->request()->getUri()->getQuery(),
         );
     }
@@ -92,7 +93,7 @@ public function testClientSerializesEmptyArraysToAnEmptyValue(): void
         // Not omitted and not a bare name: the parser reads `device_ids=`
         // as the empty array, while no param at all means unfiltered.
         $this->assertSame(
-            "device_ids=",
+            "device_ids=&_strict=true",
             $recording->request()->getUri()->getQuery(),
         );
     }
@@ -108,7 +109,7 @@ public function testClientOmitsSearchParamsSetToNull(): void
         ]);
 
         $this->assertSame(
-            "limit=20",
+            "limit=20&_strict=true",
             $recording->request()->getUri()->getQuery(),
         );
     }
@@ -124,7 +125,7 @@ public function testClientSerializesSearchParamsSetToNullValue(): void
         ]);
 
         $this->assertSame(
-            "limit=20&search=",
+            "limit=20&search=&_strict=true",
             $recording->request()->getUri()->getQuery(),
         );
     }
@@ -168,7 +169,7 @@ public function testClientSerializesSearchParamsOfEveryVerb(): void
         foreach ($verbs as $index => $verb) {
             $this->assertSame($verb, $recording->request($index)->getMethod());
             $this->assertSame(
-                "sync=true",
+                "sync=true&_strict=true",
                 $recording->request($index)->getUri()->getQuery(),
             );
         }
@@ -276,7 +277,7 @@ public function testClientSerializesTheSearchParamsOfAGeneratedRoute(): void
             $recording->request()->getUri()->getPath(),
         );
         $this->assertSame(
-            "name=Front+Door",
+            "name=Front+Door&_strict=true",
             $recording->request()->getUri()->getQuery(),
         );
     }

tests/StrictUrlSearchParamsSerializerTest.php

@@ -0,0 +1,47 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Tests;
+
+use PHPUnit\Framework\TestCase;
+use Seam\StrictUrlSearchParamsSerializer;
+use Seam\UrlSearchParams;
+
+final class StrictUrlSearchParamsSerializerTest extends TestCase
+{
+    public function testAddsStrictToNonEmptyQueryStrings(): void
+    {
+        $this->assertSame("", StrictUrlSearchParamsSerializer::serialize([]));
+        $this->assertSame(
+            "foo=d&_strict=true",
+            StrictUrlSearchParamsSerializer::serialize(["foo" => "d"]),
+        );
+    }
+
+    public function testAppendsStrictAfterTheSortedParams(): void
+    {
+        // `_strict` would sort between the uppercase and lowercase names;
+        // it is appended after the sort so it always sits last.
+        $this->assertSame(
+            "B=2&a=1&_strict=true",
+            StrictUrlSearchParamsSerializer::serialize(["a" => 1, "B" => 2]),
+        );
+    }
+
+    public function testReplacesACallerSuppliedStrictParam(): void
+    {
+        $this->assertSame(
+            "_strict=true",
+            StrictUrlSearchParamsSerializer::serialize(["_strict" => false]),
+        );
+    }
+
+    public function testUpdateCountsExistingParamsAsNonEmpty(): void
+    {
+        $search_params = new UrlSearchParams([["foo", "bar"]]);
+        StrictUrlSearchParamsSerializer::update($search_params, []);
+
+        $this->assertSame("foo=bar&_strict=true", $search_params->to_string());
+    }
+}