feat: apply the URL search params standard and type nullable params (#614)

* feat: serialize request params with the URL search params standard

The Seam API parses URL search params as complex types, so the SDK has to
build the query string itself. Serialize any mapping passed as params and
set the result on the url, rather than letting httpx encode the params with
its own rules, which represent arrays and nested objects differently.

Replace the NULL sentinel with null in request bodies as well, so a param
set to NULL is sent as null on either transport, and document how NULL
tells an explicitly null param apart from an omitted one.

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

* Apply suggestions from code review

Co-authored-by: Evan Sosenko <razorx@evansosenko.com>

* feat: type nullable params with the explicit null sentinel

Consume the blueprint isNullable flag so a param the Seam API documents as
nullable is typed to accept NULL, and a param that is merely optional is not.
Optional params are omitted by passing None, where sending null would unset a
value instead, so accepting the sentinel everywhere would invite exactly the
mistake it exists to prevent.

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

* test: name the search param tests for what they do

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

---------

Co-authored-by: Claude <noreply@anthropic.com>

Author: razor-x

README.rst

@@ -47,6 +47,8 @@ Contents
 
   * `Action Attempts`_
 
+  * `Setting a Param to Null`_
+
   * `Pagination`_
 
     * `Manually fetch pages with the next_page_cursor`_
@@ -280,6 +282,56 @@ For example:
   except SeamActionAttemptTimeoutError as e:
       print("Door took too long to unlock")
 
+Setting a Param to Null
+~~~~~~~~~~~~~~~~~~~~~~~
+
+The Seam API tells an omitted param apart from one explicitly set to null.
+In an update request, an omitted param leaves the current value unchanged,
+while a null param unsets it.
+
+Python has a single nil value `None` which represents an undefined parameter. This SDK provides an explicit null value to send in requests.
+A param set to ``None`` is omitted, and a param set to ``NULL`` is sent as `null`:
+
+.. code-block:: python
+
+  from seam import NULL, Seam
+
+  seam = Seam()
+
+  # Leaves the name unchanged.
+  seam.devices.update(device_id="your-device-id", name=None)
+
+  # Unsets the name.
+  seam.devices.update(device_id="your-device-id", name=NULL)
+
+Because unsetting a value cannot be undone, ``None`` means the safe option of
+omitting the param, and sending null is always explicit.
+This is why a param is never sent as null by default,
+even though ``None`` is the natural way to spell null in Python.
+
+``NULL`` behaves the same way in a request body and in a URL search param.
+Its type is exported as ``Null`` for annotating your own code:
+
+.. code-block:: python
+
+  from typing import Optional, Union
+
+  from seam import NULL, Null
+
+  name: Optional[Union[str, Null]] = NULL
+
+Only params the Seam API documents as nullable accept ``NULL``.
+The generated method signatures say which ones those are,
+so a type checker rejects ``NULL`` anywhere else:
+
+.. code-block:: python
+
+  # name is nullable, so it may be unset.
+  seam.devices.update(device_id="your-device-id", name=NULL)
+
+  # is_managed is not, so this fails the type check.
+  seam.devices.update(device_id="your-device-id", is_managed=NULL)
+
 Pagination
 ~~~~~~~~~~
 
@@ -562,8 +614,9 @@ 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 set to ``None`` is omitted, while a param set to ``NULL``
+is serialized to an empty value, which the Seam API reads as null,
+as described in `Setting a Param to Null`_.
 A param that cannot be represented raises a ``seam.UnserializableParamError``.
 
 The Seam API parses these params with the corresponding `parser`_.

codegen/layouts/partials/method-signature.hbs

@@ -1 +1 @@
-{{name}}(self{{#if params}}, *{{else}}{{#if (eq returnType "ActionAttempt")}}, *{{/if}}{{/if}}{{#each params}}, {{name}}: {{#if required}}{{type}}{{else}}Optional[{{type}}] = None{{/if}}{{/each}}{{#if (eq returnType "ActionAttempt")}}, wait_for_action_attempt: Optional[Union[bool, Dict[str, float]]] = None{{/if}}) -> {{returnType}}
+{{name}}(self{{#if params}}, *{{else}}{{#if (eq returnType "ActionAttempt")}}, *{{/if}}{{/if}}{{#each params}}, {{name}}: {{#if required}}{{nullableType type isNullable}}{{else}}Optional[{{nullableType type isNullable}}] = None{{/if}}{{/each}}{{#if (eq returnType "ActionAttempt")}}, wait_for_action_attempt: Optional[Union[bool, Dict[str, float]]] = None{{/if}}) -> {{returnType}}

codegen/layouts/route.hbs

@@ -2,6 +2,9 @@ from typing import Optional, Any, List, Dict, Union
 import abc
 from ..client import SeamHttpClient
 from ..route import route_metadata
+{{#if importNull}}
+from ..null import Null
+{{/if}}
 {{#if resourceClasses}}
 from ..resources import ({{#each resourceClasses}}{{this}}{{#unless @last}},{{/unless}}{{/each}})
 {{/if}}

codegen/lib/class-model.ts

@@ -4,6 +4,7 @@
 export interface ClassMethodParameter {
   name: string
   type: string
+  isNullable: boolean
   description: string
   isDeprecated: boolean
   deprecationMessage: string

codegen/lib/handlebars-helpers.ts

@@ -53,6 +53,12 @@ export const indent = (value: string, spaces: number): string =>
 export const pythonIdentifier = (name: string): string =>
   PYTHON_KEYWORDS.has(name) ? `${name}_` : name
 
+// A param the API documents as nullable may be set to the NULL sentinel, which
+// the client serializes to null. Params that are merely optional may not: they
+// are omitted by passing None, and sending null would unset a value instead.
+export const nullableType = (type: string, isNullable: boolean): string =>
+  isNullable ? `Union[${type}, Null]` : type
+
 export const isListType = (type: string): boolean => type.startsWith('List[')
 
 export const listItemType = (type: string): string => type.slice(5, -1)

codegen/lib/layouts/route.ts

@@ -23,6 +23,7 @@ export interface MethodLayoutContext {
   params: Array<{
     name: string
     type: string
+    isNullable: boolean
     description: string
     isDeprecated: boolean
     deprecationMessage: string
@@ -53,6 +54,7 @@ export interface RouteLayoutContext {
     module: string
   }>
   importResolveActionAttempt: boolean
+  importNull: boolean
   methods: MethodLayoutContext[]
 }
 
@@ -83,6 +85,7 @@ export const getMethodLayoutContext = (
   params: sortClassMethodParameters(method.parameters).map((parameter) => ({
     name: parameter.name,
     type: parameter.type,
+    isNullable: parameter.isNullable,
     description: parameter.description,
     isDeprecated: parameter.isDeprecated,
     deprecationMessage: parameter.deprecationMessage,
@@ -108,6 +111,10 @@ export const setRouteLayoutContext = (cls: ClassModel): RouteLayoutContext => {
   const abstractClassName = `Abstract${cls.name}`
   const methods = cls.methods.map(getMethodLayoutContext)
 
+  const importNull = methods.some(({ params }) =>
+    params.some(({ isNullable }) => isNullable),
+  )
+
   return {
     className: cls.name,
     abstractClassName,
@@ -131,6 +138,7 @@ export const setRouteLayoutContext = (cls: ClassModel): RouteLayoutContext => {
       module: `${cls.namespace}_${identifier.namespace}`,
     })),
     importResolveActionAttempt,
+    importNull,
     methods,
   }
 }

codegen/lib/routes.ts

@@ -99,6 +99,7 @@ export const routes = (
         parameters: endpoint.request.parameters.map((parameter) => ({
           name: parameter.name,
           type: mapParameterToPythonType(parameter),
+          isNullable: parameter.isNullable,
           description: parameter.description,
           isDeprecated: parameter.isDeprecated,
           deprecationMessage: parameter.deprecationMessage,

seam/client.py

@@ -1,3 +1,4 @@
+from collections.abc import Mapping
 from typing import Any, Dict, Optional
 from importlib.metadata import version
 import abc
@@ -12,6 +13,8 @@
     SeamHttpInvalidInputError,
     SeamHttpUnauthorizedError,
 )
+from .null import replace_null
+from .url_search_params_serializer import serialize_url_search_params
 
 SDK_HEADERS = {
     "seam-sdk-name": "seamapi/python",
@@ -102,6 +105,12 @@ def delete(self, url, json=None, **kwargs) -> Any:
         return self.request("DELETE", url, json=json, **kwargs)
 
     def request(self, method, url, *args, **kwargs) -> Any:
+        if isinstance(kwargs.get("params"), Mapping):
+            url = with_search_params(url, kwargs.pop("params"))
+
+        if "json" in kwargs:
+            kwargs["json"] = replace_null(kwargs["json"])
+
         response = super().request(method, url, *args, **kwargs)
 
         return self._handle_response(response)
@@ -142,6 +151,15 @@ def _handle_error_response(self, response: Response):
         raise SeamHttpApiError(error_details, status_code, request_id)
 
 
+def with_search_params(url: Any, params: Mapping[str, Any]) -> Any:
+    query = serialize_url_search_params(params)
+
+    if not query:
+        return url
+
+    return httpx.URL(url, query=query.encode())
+
+
 def is_api_error_response(response: Response) -> bool:
     try:
         content_type = response.headers.get("content-type", "")

seam/null.py

@@ -10,6 +10,7 @@
 Sending null is explicit and always spelled :data:`NULL`.
 """
 
+from collections.abc import Mapping, Sequence
 from typing import Any
 
 
@@ -60,3 +61,27 @@ def is_null(value: Any) -> bool:
     :returns: Whether the value is the ``NULL`` sentinel"""
 
     return isinstance(value, Null)
+
+
+def replace_null(value: Any) -> Any:
+    """Returns a copy of a value with every :data:`NULL` sentinel replaced by ``None``.
+
+    The sentinel only distinguishes an explicit null from an omitted param
+    within this SDK. Once a request body is being serialized, the param is
+    known to be present, so the sentinel becomes the null that JSON has.
+
+    :param value: The value to copy
+    :type value: Any
+
+    :returns: The value with each ``NULL`` sentinel replaced by ``None``"""
+
+    if is_null(value):
+        return None
+
+    if isinstance(value, Mapping):
+        return {key: replace_null(item) for key, item in value.items()}
+
+    if isinstance(value, Sequence) and not isinstance(value, (str, bytes)):
+        return [replace_null(item) for item in value]
+
+    return value