feat: send explicit null request params with seam.NULL

The Seam API distinguishes an omitted param from a param explicitly set to
null: in an update request, an omitted param leaves the current value
unchanged while a null param unsets it, and some endpoints accept null as a
meaningful filter value. Python has a single absence value, so route methods
omitted both cases and there was no way to send null. For example,
access_grants.list documents null as a filter for Access Grants without an
access_grant_key, but passing None dropped the filter and returned every
Access Grant.

Add the NULL sentinel for a param explicitly set to null. Since sending null
is rarely intended and unsetting a value cannot be undone, None keeps meaning
the safe option of omitting the param, so this adds the capability without
changing the behavior of any existing call.

The existing generated route methods need no change: they already omit params
set to None, and the client now replaces any remaining NULL sentinel with None
so that json serializes it to null. NULL works at any depth, e.g., to clear a
single key of an object param.

Bind the URL search params serializer to the same convention, replacing its
UNDEFINED sentinel: None is JavaScript undefined and is removed, while NULL is
JavaScript null and serializes to an empty value.

NULL is typed as Any so it may be passed to any param without a type error.
Once blueprint exposes isNullable on Parameter, codegen can type nullable
params precisely instead.

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

Author: claude

README.rst

@@ -61,6 +61,8 @@ Contents
 
   * `Webhooks`_
 
+  * `Omitted params and null params`_
+
   * `Advanced Usage`_
 
     * `Setting the endpoint`_
@@ -427,6 +429,45 @@ see the `Svix docs for more examples in specific frameworks <https://docs.svix.c
       app.run(port=8080)
 
 
+Omitted params and null params
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The Seam API distinguishes an omitted param from a param explicitly set to null.
+In an update request, an omitted param leaves the current value unchanged,
+while a null param unsets the current value.
+Some endpoints also accept null as a meaningful filter value.
+
+Python has a single absence value, so this SDK maps the two cases as follows:
+
+- ``None``, or simply not passing the param, omits it from the request.
+- ``seam.NULL`` sends the param as null.
+
+Sending null is rarely intended and unsetting a value cannot be undone,
+so ``None`` means the safe option of omitting the param
+and sending null is always explicit:
+
+.. code-block:: python
+
+  from seam import NULL, Seam
+
+  seam = Seam()
+
+  # Unsets the device name.
+  seam.devices.update(device_id=device_id, name=NULL)
+
+  # Leaves the device name unchanged.
+  seam.devices.update(device_id=device_id, name=None)
+
+  # Lists only the Access Grants which have no access_grant_key.
+  seam.access_grants.list(access_grant_key=NULL)
+
+``NULL`` may be used at any depth, e.g., to clear a single key
+while leaving the other keys unchanged:
+
+.. code-block:: python
+
+  seam.spaces.update(space_id=space_id, customer_data={"check_in": NULL})
+
 Advanced Usage
 ~~~~~~~~~~~~~~
 
@@ -462,8 +503,9 @@ Use it directly when building requests to the Seam API by hand:
 
 Params are sorted by name, so equivalent input always produces the same query string.
 Nested dicts are serialized to dot-path keys, e.g., ``{"a": {"b": 1}}`` becomes ``a.b=1``.
-Params set to ``None`` are serialized to an empty value, e.g., ``a=``,
-while params set to ``seam.UNDEFINED`` are removed.
+Params set to ``None`` are omitted,
+while params set to ``seam.NULL`` are serialized to an empty value, e.g., ``a=``.
+See `Omitted params and null params`_.
 A param that cannot be represented raises a ``seam.UnserializableParamError``.
 
 To merge serialized params into existing params, use ``update_url_search_params``:

seam/__init__.py

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

seam/client.py

@@ -11,6 +11,7 @@
     SeamHttpInvalidInputError,
     SeamHttpUnauthorizedError,
 )
+from .null import replace_null
 
 SDK_HEADERS = {
     "seam-sdk-name": "seamapi/python",
@@ -59,6 +60,12 @@ def __init__(
 
     def request(self, method, url, *args, **kwargs):
         url = urljoin(self.base_url, url)
+
+        # Route methods omit params set to None, so any remaining NULL sentinel
+        # is an explicit null and becomes None for JSON serialization.
+        if "json" in kwargs:
+            kwargs["json"] = replace_null(kwargs["json"])
+
         response = super().request(method, url, *args, **kwargs)
 
         return self._handle_response(response)

seam/null.py

@@ -0,0 +1,95 @@
+"""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 collections.abc import Mapping
+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: Any = Null()
+"""Sentinel for a param explicitly set to null.
+
+Params set to this sentinel are sent as null,
+whereas params set to ``None`` are omitted from the request.
+
+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:
+
+.. code-block:: python
+
+  from seam import NULL, Seam
+
+  seam = Seam()
+
+  # Unsets the name, leaving custom_metadata unchanged.
+  seam.devices.update(device_id=device_id, name=NULL)
+
+  # Lists only the Access Grants which have no access_grant_key.
+  seam.access_grants.list(access_grant_key=NULL)
+
+This sentinel is typed as ``Any`` so that it may be passed
+to any param without a type error.
+"""
+
+
+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)
+
+
+def replace_null(value: Any) -> Any:
+    """Recursively replaces the :data:`NULL` sentinel with ``None``.
+
+    Returns a copy, so the given value is never modified.
+    Use this to prepare a request payload for JSON serialization,
+    where ``None`` is serialized to null.
+
+    :param value: The value to convert
+    :type value: Any
+
+    :returns: A copy of the value with every ``NULL`` sentinel replaced"""
+
+    if is_null(value):
+        return None
+
+    if isinstance(value, Mapping):
+        return {key: replace_null(item) for key, item in value.items()}
+
+    if isinstance(value, list):
+        return [replace_null(item) for item in value]
+
+    if isinstance(value, tuple):
+        return tuple(replace_null(item) for item in value)
+
+    return value

seam/utils/url_search_params_serializer.py

@@ -12,8 +12,10 @@
 
 Type mapping between the reference implementation and this port:
 
-- JavaScript ``undefined`` is :data:`UNDEFINED`, or simply an absent key.
-- JavaScript ``null`` is ``None``.
+- JavaScript ``undefined`` is ``None``, or simply an absent key.
+- JavaScript ``null`` is :data:`seam.NULL <seam.null.NULL>`.
+  Python has a single absence value, so ``None`` means the safe option of
+  omitting the param and sending null is always explicit.
 - JavaScript ``string`` is ``str``.
 - JavaScript ``boolean`` is ``bool``.
 - JavaScript ``number`` is ``float`` or ``int``.
@@ -38,6 +40,8 @@
 from typing import Any, Iterator, List, Optional, Sequence, Tuple, Union
 from urllib.parse import parse_qsl
 
+from ..null import is_null
+
 Params = Mapping[str, Any]
 
 
@@ -60,31 +64,6 @@ def __init__(self, name: str, message: str):
         self.name = name
 
 
-class _Undefined:
-    """Type of the :data:`UNDEFINED` sentinel."""
-
-    _instance = None
-
-    def __new__(cls):
-        if cls._instance is None:
-            cls._instance = super().__new__(cls)
-        return cls._instance
-
-    def __repr__(self):
-        return "UNDEFINED"
-
-    def __bool__(self):
-        return False
-
-
-UNDEFINED = _Undefined()
-"""Sentinel for the absence of a value, equivalent to JavaScript ``undefined``.
-
-Params set to this sentinel are removed, whereas params set to ``None``
-are serialized to an empty value. Omitting the key entirely is equivalent.
-"""
-
-
 class UrlSearchParams:
     """A mutable collection of URL search params.
 
@@ -296,7 +275,7 @@ def _nested_update_url_search_params(
 
         name = ".".join(current_path)
 
-        if _is_undefined(value):
+        if value is None:
             continue
 
         if isinstance(value, str) and len(value) == 0:
@@ -328,7 +307,7 @@ def _update_url_search_params_from_array(
             "is an array containing the empty string which is unsupported",
         )
 
-    if any(value is None or _is_undefined(value) for value in values):
+    if any(value is None or is_null(value) for value in values):
         raise UnserializableParamError(
             name,
             "is an array containing null or undefined values which is unsupported",
@@ -339,7 +318,7 @@ def _update_url_search_params_from_array(
 
 
 def _serialize(name: str, value: Any) -> str:
-    if value is None:
+    if is_null(value):
         return ""
 
     if isinstance(value, str):
@@ -364,10 +343,6 @@ def _is_empty_string(value: Any) -> bool:
     return isinstance(value, str) and len(value) == 0
 
 
-def _is_undefined(value: Any) -> bool:
-    return isinstance(value, _Undefined)
-
-
 def _format_datetime(value: datetime.datetime) -> str:
     if value.tzinfo is None:
         value = value.replace(tzinfo=datetime.timezone.utc)

test/null_test.py

@@ -0,0 +1,110 @@
+from collections import OrderedDict
+
+import niquests
+import pytest
+
+from seam.client import SeamHttpClient
+from seam.null import NULL, Null, is_null, replace_null
+
+
+def test_null_is_a_singleton():
+    assert Null() is NULL
+    assert is_null(NULL)
+    assert is_null(Null())
+
+
+def test_null_is_not_none():
+    assert NULL is not None
+    assert not is_null(None)
+    assert not is_null("")
+    assert not is_null(0)
+
+
+def test_null_is_falsy():
+    assert not NULL
+
+
+def test_null_repr():
+    assert repr(NULL) == "NULL"
+
+
+def test_replace_null():
+    assert replace_null(NULL) is None
+    assert replace_null(None) is None
+    assert replace_null("a") == "a"
+    assert replace_null(0) == 0
+    assert replace_null(False) is False
+
+
+def test_replace_null_in_dict():
+    assert replace_null({"a": NULL, "b": 1, "c": None}) == {
+        "a": None,
+        "b": 1,
+        "c": None,
+    }
+
+
+def test_replace_null_in_nested_dict():
+    assert replace_null({"a": {"b": {"c": NULL}}}) == {"a": {"b": {"c": None}}}
+
+
+def test_replace_null_in_lists_and_tuples():
+    assert replace_null(["a", NULL]) == ["a", None]
+    assert replace_null(("a", NULL)) == ("a", None)
+    assert replace_null({"a": [{"b": NULL}]}) == {"a": [{"b": None}]}
+
+
+def test_replace_null_does_not_modify_the_given_value():
+    params = {"a": NULL, "b": [NULL]}
+    replace_null(params)
+
+    assert params == {"a": NULL, "b": [NULL]}
+
+
+def test_replace_null_normalizes_mappings_to_dicts():
+    result = replace_null(OrderedDict([("a", NULL)]))
+
+    assert result == {"a": None}
+
+
+class StubResponse:
+    status_code = 200
+    headers = {"content-type": "application/json"}
+
+    def json(self):
+        return {}
+
+
+@pytest.fixture(name="sent_payloads")
+def sent_payloads_fixture(monkeypatch):
+    payloads = []
+
+    # pylint: disable=unused-argument
+    def request(self, method, url, *args, **kwargs):
+        payloads.append(kwargs.get("json"))
+        return StubResponse()
+
+    monkeypatch.setattr(niquests.Session, "request", request)
+
+    return payloads
+
+
+def test_client_sends_null_params_as_json_null(sent_payloads):
+    client = SeamHttpClient(base_url="https://example.com", auth_headers={})
+    client.post("/devices/update", json={"device_id": "a", "name": NULL})
+
+    assert sent_payloads == [{"device_id": "a", "name": None}]
+
+
+def test_client_sends_nested_null_params_as_json_null(sent_payloads):
+    client = SeamHttpClient(base_url="https://example.com", auth_headers={})
+    client.post("/spaces/update", json={"customer_data": {"check_in": NULL}})
+
+    assert sent_payloads == [{"customer_data": {"check_in": None}}]
+
+
+def test_client_passes_through_payloads_without_null_params(sent_payloads):
+    client = SeamHttpClient(base_url="https://example.com", auth_headers={})
+    client.post("/devices/update", json={"device_id": "a", "name": "Front Door"})
+
+    assert sent_payloads == [{"device_id": "a", "name": "Front Door"}]