feat: implement the URL search params serialization standard

Port @seamapi/url-search-params-serializer to Python. It defines how the Seam
SDKs and other API consumers serialize objects to URL search params, and the
Seam API parses them with the corresponding parser.

Output is byte-for-byte identical to the reference implementation:

- Values are encoded with the application/x-www-form-urlencoded serializer,
  which differs from urllib in its treatment of "*" and "~".
- Params are sorted by name, compared by UTF-16 code unit.
- Floats are formatted using the ECMAScript Number::toString algorithm, which
  differs from repr for integral floats and around the exponent notation
  thresholds.

The serialization defines the name and value of each param, where every value
is a string, and leaves rendering the query string to URLSearchParams.
UrlSearchParams is that layer here.

Python has a single absence value, and the standard needs both: a param set to
None is omitted, while a param set to NULL is serialized to an empty value,
which the API reads as null.

Nothing calls this yet. Serializing the params of a request is a separate
change.

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

Author: claude

README.rst

@@ -73,6 +73,8 @@ Contents
 
     * `Configuring the httpx client`_
 
+    * `Serializing URL search params`_
+
 * `Development and Testing`_
 
   * `Quickstart`_
@@ -518,6 +520,58 @@ precedence over the defaults the SDK sets:
         },
     )
 
+Serializing URL search params
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The Seam API parses URL search params as complex types.
+If you call it with your own HTTP client,
+``serialize_url_search_params`` is exported for that purpose:
+
+.. code-block:: python
+
+  import httpx
+  from seam import serialize_url_search_params
+
+  httpx.get(
+      "https://connect.getseam.com/devices/list",
+      params=serialize_url_search_params({"device_ids": ["device1", "device2"]}),
+      headers={"Authorization": "Bearer your-api-key"},
+  )
+
+The serialization defines the name and value of each search param,
+where every value is a string.
+``UrlSearchParams`` holds those pairs and renders the query string,
+as `URLSearchParams`_ does for the `reference implementation`_:
+
+.. code-block:: python
+
+  from seam import UrlSearchParams, update_url_search_params
+
+  search_params = UrlSearchParams()
+
+  update_url_search_params(search_params, {"device_ids": ["device1", "device2"]})
+
+  list(search_params)
+  # => [('device_ids', 'device1'), ('device_ids', 'device2')]
+
+  str(search_params)
+  # => 'device_ids=device1&device_ids=device2'
+
+Pass either the query string or the pairs to your HTTP client.
+A client may percent-encode a few characters differently than
+``URLSearchParams`` does, e.g. httpx escapes ``*`` and unescapes ``~``,
+which the Seam API reads as the same params either way.
+
+A param set to ``None`` is omitted, while a param set to ``seam.NULL``
+is serialized to an empty value, which the Seam API reads as null.
+A param that cannot be represented raises a ``seam.UnserializableParamError``.
+
+The Seam API parses these params with the corresponding `parser`_.
+
+.. _URLSearchParams: https://developer.mozilla.org/en-US/docs/Web/API/URLSearchParams
+.. _reference implementation: https://github.com/seamapi/url-search-params-serializer
+.. _parser: https://github.com/seamapi/url-search-params-parser
+
 Development and Testing
 -----------------------
 

seam/__init__.py

@@ -15,3 +15,10 @@
 )
 from .seam_webhook import SeamWebhook
 from svix.webhooks import WebhookVerificationError as SeamWebhookVerificationError
+from .null import NULL, Null
+from .url_search_params_serializer import (
+    UnserializableParamError,
+    UrlSearchParams,
+    serialize_url_search_params,
+    update_url_search_params,
+)

seam/null.py

@@ -0,0 +1,62 @@
+"""The explicit null sentinel used by request params.
+
+Python has a single absence value, ``None``, but the Seam API distinguishes
+an omitted param from a param explicitly set to null. For example, in an
+update request, an omitted param leaves the current value unchanged,
+while a null param unsets the current value.
+
+Since sending null is rarely intended and unsetting a value cannot be undone,
+``None`` means the safe option of omitting the param.
+Sending null is explicit and always spelled :data:`NULL`.
+"""
+
+from typing import Any
+
+
+class Null:
+    """Type of the :data:`NULL` sentinel."""
+
+    _instance = None
+
+    def __new__(cls):
+        if cls._instance is None:
+            cls._instance = super().__new__(cls)
+        return cls._instance
+
+    def __repr__(self):
+        return "NULL"
+
+    def __bool__(self):
+        return False
+
+
+NULL = Null()
+"""Sentinel for a param explicitly set to null.
+
+Params set to this sentinel are serialized to null,
+whereas params set to ``None`` are omitted:
+
+.. code-block:: python
+
+  from seam import NULL, serialize_url_search_params
+
+  serialize_url_search_params({"name": NULL, "limit": 20})
+  # => 'limit=20&name='
+
+  serialize_url_search_params({"name": None, "limit": 20})
+  # => 'limit=20'
+
+Use it wherever the Seam API documents null as a meaningful value, e.g.,
+to unset a value in an update request, or to filter by an unset value.
+"""
+
+
+def is_null(value: Any) -> bool:
+    """Returns whether a value is the :data:`NULL` sentinel.
+
+    :param value: The value to check
+    :type value: Any
+
+    :returns: Whether the value is the ``NULL`` sentinel"""
+
+    return isinstance(value, Null)