feat: type nullable request params precisely

Blueprint now reports isNullable for request parameters, so codegen can
distinguish the params the Seam API documents as nullable from the rest.
Type a nullable param as Union[T, Null] so it accepts the NULL sentinel, and
leave every other param as it was.

This makes NULL checkable. Previously NULL had to be typed as Any to be
passed anywhere, which meant a type checker could not report sending null to
a param that does not accept it. NULL is now typed as Null, so passing it to
a non-nullable param such as devices.update(is_managed=...) is an error while
access_grants.list(access_grant_key=NULL) is accepted.

Reading isNullable requires blueprint 1.4.0 or later, which turns an
untyped property from a warning into an error. The pinned types release
leaves submit_args untyped for /seam/connect_webview/v1/submit, so generation
fails against it; bump types to the next release, which defines that type and
adds the between parameter to events.list.

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

Author: claude

README.rst

@@ -444,7 +444,9 @@ Python has a single absence value, so this SDK maps the two cases as follows:
 
 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:
+and sending null is always explicit.
+Route methods accept ``NULL`` only for the params the Seam API documents as
+nullable, so a type checker reports passing it to any other param as an error:
 
 .. code-block:: python
 

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

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

codegen/lib/class-model.ts

@@ -9,6 +9,7 @@ export interface ClassMethodParameter {
   deprecationMessage: string
   position?: number | undefined
   required?: boolean | undefined
+  isNullable?: boolean | undefined
 }
 
 export interface ClassMethod {

codegen/lib/handlebars-helpers.ts

@@ -56,3 +56,8 @@ export const pythonIdentifier = (name: string): string =>
 export const isListType = (type: string): boolean => type.startsWith('List[')
 
 export const listItemType = (type: string): string => type.slice(5, -1)
+
+// A nullable param accepts the NULL sentinel, which is sent as null.
+// A param set to None is omitted from the request instead.
+export const nullableType = (type: string, isNullable: boolean): string =>
+  isNullable ? `Union[${type}, Null]` : type

codegen/lib/layouts/route.ts

@@ -22,6 +22,7 @@ export interface MethodLayoutContext {
     isDeprecated: boolean
     deprecationMessage: string
     required: boolean
+    isNullable: boolean
   }>
   returnPath: string[]
   returnType: string
@@ -67,6 +68,7 @@ export const getMethodLayoutContext = (
     isDeprecated: parameter.isDeprecated,
     deprecationMessage: parameter.deprecationMessage,
     required: parameter.required ?? false,
+    isNullable: parameter.isNullable ?? false,
   })),
   returnPath: method.returnPath,
   returnType: method.returnResource,

codegen/lib/routes.ts

@@ -101,6 +101,7 @@ export const routes = (
           deprecationMessage: parameter.deprecationMessage,
           position: parameter.name === idParameterName ? 0 : undefined,
           required: parameter.isRequired,
+          isNullable: parameter.isNullable,
         })),
         ...resolveResponse(response),
       })

package-lock.json

@@ -28,10 +28,10 @@
     }
   },
   "devDependencies": {
-    "@seamapi/blueprint": "^1.1.0",
+    "@seamapi/blueprint": "^1.4.0",
     "@seamapi/fake-seam-connect": "1.86.0",
     "@seamapi/smith": "^1.1.0",
-    "@seamapi/types": "1.983.0",
+    "@seamapi/types": "1.984.0",
     "change-case": "^5.4.4",
     "prettier": "^3.2.5"
   }

package.json

@@ -31,7 +31,7 @@ def __bool__(self):
         return False
 
 
-NULL: Any = Null()
+NULL = Null()
 """Sentinel for a param explicitly set to null.
 
 Params set to this sentinel are sent as null,
@@ -52,8 +52,8 @@ def __bool__(self):
   # 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.
+Route methods accept this sentinel only for params the Seam API
+documents as nullable, so passing it to any other param is a type error.
 """