docs: Add handoff spec for fixing nested resource types

Generated resource dataclasses declare nested object properties as
Dict[str, Any] while from_dict assigns a DeepAttrDict, so the intended
attribute access does not type check and nested properties have no
generated docs or completion. Nested unknown keys are also never
stripped, which makes the SDK-level property guarantee shallower here
than in the PHP SDK.

Document the codegen changes required to generate a dataclass per nested
object, the dict-compatibility shim needed to avoid breaking subscript
access, and two independent gaps: the package ships no py.typed marker,
and no type checker is wired into lint.

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

Author: claude

NESTED_RESOURCES.md

@@ -0,0 +1,256 @@
+# Fix nested resource types in the Python SDK
+
+## Task
+
+Nested properties on generated resource dataclasses have **no types, no docs, and
+no autocomplete**, and the declared annotation *contradicts* the runtime object.
+Fix this by generating a dataclass per nested object, so nested properties get
+real types, real docstrings, and completion — and so the annotation matches what
+`from_dict` actually assigns.
+
+All generated code lives in `seam/resources/` and `seam/routes/` and is produced
+by `codegen/`. **Do not hand-edit generated files** — change the templates and
+regenerate (`npm run generate`).
+
+---
+
+## The problem, concretely
+
+`seam/resources/device.py:118` declares:
+
+```python
+properties: Dict[str, Any]
+```
+
+but `from_dict` (line 173) assigns a different type entirely:
+
+```python
+properties=DeepAttrDict(d.get("properties", None)),
+```
+
+Consequences:
+
+| Expression | Runtime | Type checker |
+|---|---|---|
+| `device.properties.locked` | works | **error** — `Dict[str, Any]` has no attribute `locked` |
+| `device.properties["locked"]` | works | passes, returns `Any` — no completion, no docs |
+
+So the access pattern the SDK is designed for does not type-check, and the one
+that type-checks tells you nothing.
+
+**Docs are top-level only.** `codegen/layouts/partials/resource-dataclass.hbs`
+iterates `properties` exactly once and emits a flat `:ivar` list, so nested
+shapes are undocumented. The only mention of any nested field name in all of
+`device.py` is incidental prose inside a *different* field's docstring:
+
+```
+:ivar display_name: Display name of the device, defaults to nickname (if it is
+  set) or ``properties.appearance.name``, otherwise.
+```
+
+**`errors`/`warnings` are worse than nested objects.** They are
+`List[Dict[str, Any]]` and, unlike `properties`, are *not* wrapped at all
+(`errors=d.get("errors", None)`, line 169). So `device.errors[0].error_code`
+raises `AttributeError` — subscript access is mandatory. Compare Ruby, which
+coerces these into real `ResourceError` objects where `.error_code` works.
+
+**Nested unknown keys are never stripped.** Because nested objects are
+untyped passthrough, `device.properties.anything_new` resolves. This is why
+Python's LTS enforcement is shallower than PHP's — PHP is the only SDK where the
+known-property guarantee holds at depth. Generating nested dataclasses closes
+that gap as a side effect, and that is a primary benefit of this change, not an
+incidental one.
+
+---
+
+## Approach
+
+Mirror the PHP SDK, which generates a class per nested object (74 of them for
+`Device` alone) and is the only SDK where the guarantee holds deeply.
+
+Blueprint already exposes the nested shape — the JS templates in
+`seamapi/javascript-http` consume `properties`, `itemProperties`, and `variants`
+today — so **no upstream `@seamapi/blueprint` change is needed**.
+
+### 1. `codegen/lib/layouts/resources.ts` — recurse and register nested classes
+
+Currently `getResourceLayoutContexts` builds a flat property list and never
+recurses. Add a registry of nested classes discovered while walking each
+resource's properties:
+
+- `format: 'object'` → nested class from `property.properties`
+- `format: 'list'` with `itemFormat: 'object'` → nested class from `property.itemProperties`
+- `format: 'list'` with `itemFormat: 'discriminated_object'` → merge `variants`
+  properties, reusing the existing `mergeResourceProperties` helper (line 34)
+- `format: 'record'` → **leave as `Dict[str, Any]`.** This is genuinely
+  free-form JSON (`custom_metadata`) and must stay passthrough. Do not generate a
+  class for it and do not strip its keys.
+
+Name nested classes `{ResourceClass}{PascalCasePropertyPath}`, matching PHP:
+`DeviceProperties`, `DeviceBattery`, `DeviceAppearance`. Dedupe by class name —
+PHP does `if (classes.has(name)) return`, and the same collision is expected here
+(e.g. shared sub-shapes between `errors` and `warnings`).
+
+Note the existing `isDictParam` hack becomes unnecessary for object properties:
+
+```ts
+isDictParam: type.startsWith('Dict') || property.name === 'properties',
+```
+
+The `|| property.name === 'properties'` special case exists only to force
+attribute access on `device.properties`. Once `properties` has a real class, drop
+the special case and keep `isDictParam` for true `record` properties only.
+
+### 2. `codegen/lib/python-type.ts` — return nested class names
+
+`mapPropertyToPythonType` currently maps both `object` and `record` to
+`Dict[str, Any]`. It must return the generated class name when one exists.
+
+This means it can no longer be a pure per-property function — build the nested
+class registry **first**, then thread it into type mapping. Restructure rather
+than trying to keep the current signature.
+
+Leave the scalar mapping alone: `datetime`/`id`/`enum` → `str` stays as-is (see
+Out of scope).
+
+### 3. `codegen/layouts/resource.hbs` and `resource-dataclass.hbs`
+
+Emit multiple dataclasses per module. **Nested classes must be defined before the
+parent** — dataclass field annotations are evaluated at class-creation time, so
+definition order matters. (Alternatively add `from __future__ import annotations`,
+but ordering is simpler and clearer in generated output.)
+
+Hydration in `from_dict`:
+
+```python
+# object
+properties=DeviceProperties.from_dict(d.get("properties")) if d.get("properties") is not None else None,
+
+# list of objects
+errors=[DeviceErrors.from_dict(i) for i in d.get("errors") or []],
+```
+
+Use `or []` rather than `d.get("errors", [])` so an explicit `null` from the API
+also yields `[]` rather than crashing the comprehension.
+
+**Emit `:ivar` docs for nested classes too.** This is the actual user-facing win —
+each nested class gets the same generated docstring treatment the top-level
+resource gets today.
+
+### 4. Backwards compatibility — read this carefully
+
+`device.properties` is currently a `DeepAttrDict`, which subclasses `dict`. So all
+of this works today and will break under a bare dataclass:
+
+```python
+device.properties["locked"]
+device.properties.get("locked")
+"locked" in device.properties
+for k in device.properties: ...
+json.dumps(device.properties)
+```
+
+Add a small hand-written mixin under `seam/utils/` that generated nested classes
+inherit, providing `__getitem__`, `get`, `__contains__`, `__iter__`, and `keys`.
+That keeps both access styles working. Only `dict(...)` and
+`isinstance(x, dict)` would still break, which is an acceptable and documentable
+narrowing.
+
+**One intentional behavior change to call out in the changelog:** today
+`device.properties.typo` silently returns an empty `DeepAttrDict` *and mutates the
+object*, inserting the typo'd path (see `seam/utils/deep_attr_dict.py:19-25`).
+With dataclasses it raises `AttributeError`. That is strictly better — it matches
+Ruby, and it turns silent typos into errors — but it is a behavior change and
+someone may be relying on the falsy-empty-dict result.
+
+### 5. Add `seam/py.typed`
+
+There is **no `py.typed` marker anywhere in the repo**. Per PEP 561 that means
+mypy treats the entire `seam` package as untyped and ignores every annotation.
+Pyright/Pylance reads it anyway (`useLibraryCodeForTypes` defaults on), which is
+why top-level completion appears to work in VS Code while mypy users get nothing.
+
+Create an empty `seam/py.typed` and add it to the Poetry package data in
+`pyproject.toml` so it ships in the wheel.
+
+This is independent of the rest of the work and can land first.
+
+### 6. Add a type checker to lint
+
+`just lint` is `pylint` + `black --check` + `rstcheck`. There is no mypy or
+pyright in `pyproject.toml` devDeps, so **the repo currently cannot verify any
+typing claim it makes** — which is how the `Dict[str, Any]` vs `DeepAttrDict`
+mismatch survived.
+
+Add mypy or pyright to devDeps and to `just lint`. Without this there is no
+regression gate on the thing being fixed.
+
+---
+
+## Out of scope
+
+**Date parsing.** `codegen/lib/python-type.ts` maps `datetime` → `str`, so
+`created_at` is a string. Ruby parses these to `Time` via `date_accessor`.
+Bringing Python to parity is a larger breaking change and belongs in a separate
+task. Do not change it here.
+
+---
+
+## Tests
+
+pytest, via `just test` (`poetry run pytest --cov=./seam`). Fixtures live in
+`test/conftest.py` and run against `@seamapi/fake-seam-connect`.
+
+Add coverage for:
+
+- nested object hydration — `device.properties` is a `DeviceProperties`, and
+  `device.properties.locked` returns the right value
+- list-of-objects hydration — `device.errors[0].error_code` works via
+  **attribute** access (this is the regression the change is meant to fix)
+- unknown **nested** key is dropped
+- `record` properties (`custom_metadata`) still pass through untouched, including
+  unknown keys
+- dict-compat shims: `["locked"]`, `.get()`, `in`, iteration
+- missing nested object → `None`, missing nested list → `[]`
+- a union resource (`action_attempt`) hydrates its nested `result`/`error`
+
+Note `seam/utils/deep_attr_dict_test.py` exists and tests `DeepAttrDict`
+directly. If `DeepAttrDict` remains in use for `record` properties, keep it and
+its test; only remove it if nothing references it after the change.
+
+---
+
+## Verification
+
+```
+cd /home/user/python
+npm ci
+npm run generate     # must be idempotent; review the seam/resources/ diff
+just lint
+just test
+```
+
+Then confirm by inspection:
+
+- `seam/resources/device.py` declares `properties: DeviceProperties` (not
+  `Dict[str, Any]`), and `DeviceProperties` is defined above `Device` in the file
+  with its own `:ivar` docstrings
+- `custom_metadata` is still `Dict[str, Any]`
+- in an editor with Pylance, `device.properties.` offers completions and
+  `device.errors[0].error_code` no longer errors
+
+CI regenerates on every non-`main` push and auto-commits `ci: Generate code`
+(`.github/workflows/generate.yml`), so the generated diff is the real regression
+gate — make sure it is clean and reviewed, not just green.
+
+---
+
+## Release note
+
+This changes the runtime type of every nested resource property and starts
+dropping unknown nested keys. Treat it as a **major** release, and document:
+
+- nested properties are now typed objects, not `dict` subclasses
+- `dict(...)` / `isinstance(x, dict)` on a nested property no longer works
+- a typo'd nested attribute now raises `AttributeError` instead of returning `{}`
+- previously-visible undocumented nested API fields are now stripped