refactor: fold the platform client into a shared facade base

PR #29 gave the platform client its own copy of the transport: the pool,
the close/reopen handling and the httpx-to-requests exception translation
were duplicated from APIDeploymentsClient, and the copy had no retry policy
at all. Two copies of that code drift; only one of them was getting fixes.

Both clients now inherit `_HttpxFacade`, which owns the lazily built pooled
transport, `close`/context-manager support, the exception translation and the
retry-with-Retry-After policy. A client subclass supplies its error class and
its methods, nothing else. That drops ~184 duplicated lines and gives the
platform operations the retry behaviour the README already promised.

Three defects fall out of sharing the code:

- The transport pool is now built inside the lock. `AuthenticatedClient
  .get_httpx_client()` builds lazily and unsynchronised, so publishing the
  client before warming it let two threads build two pools.
- A close during flight no longer escapes untranslated. httpx answers a send
  on a closed client with a bare `RuntimeError`, which is not in the subtree
  `_translate_transport_errors` covers, so it reached callers catching the
  documented `requests` types. It is translated at the send.
- `list_deployments` no longer sends `workflow=None`. The generated builder
  renders that parameter with `str()` before it filters `None` out, so the
  literal string "None" went on the wire as a filter matching no workflow on
  every otherwise unfiltered call. Unset filters are omitted instead, which
  also holds if the generator special-cases another parameter later.

Exceptions get a hierarchy. `APIDeploymentsClientException` never worked --
its `__init__` nested three more `def`s that were never bound to the class,
so `message` was dropped and `Exception.__init__` was never called, leaving
`str(e)` empty and the documented `error_message()` non-existent. It is now
an alias of a new `UnstractError` base, with `APIDeploymentError` and
`PlatformClientError` beneath it. Catching the old name still catches both
clients, including anything added later.

Also here:

- The generated models are re-exported, so callers who want typing can
  `WhoAmIResponse.from_dict(...)` instead of us hand-writing a mirror of the
  spec that regeneration would not update. Facade methods keep returning
  `dict[str, Any]`.
- The platform client gets its own logger. Both clients shared the module
  logger, so levelling one re-levelled the other, switching a live sibling's
  debug output -- which includes response bodies -- on or off as a side effect.
- A 2xx body that is unreadable, or JSON that is not an object, is now an
  error naming what arrived rather than an `AttributeError` downstream. The
  ERROR log for it is bounded to the same excerpt the exception carries.
- An `org_id` that is empty or blank is refused before the request, and a path
  on `base_url` is warned about rather than silently discarded by `urljoin`.
- `.claude/skills/spec-upgrade/SKILL.md` step 5 gains the recipe for adding an
  operation: which class it belongs to, the method shape, and why it builds
  from `_get_kwargs` rather than `sync_detailed`.

No runtime breaking change. The one visible shift is `type(e).__name__`, which
becomes `APIDeploymentError` where it was `APIDeploymentsClientException`;
`except APIDeploymentsClientException` is unaffected.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01CnhmFYFRBrK376tZyDtwUM

Author: chandrasekharan-zipstack

.claude/skills/spec-upgrade/SKILL.md

@@ -71,6 +71,31 @@ Upstream, the spec is produced by the backend that serves these endpoints
    the facade is where it becomes public API. Fixes belong here or upstream in
    the spec, never in the generated tree — regeneration overwrites that wholesale.
 
+   A new operation belongs to `APIDeploymentsClient` if it takes a deployment
+   key, `PlatformKeyClient` if it takes a platform key, otherwise a new subclass
+   of `_HttpxFacade` — never a free-standing class, or the transport, retry and
+   exception translation get reimplemented and drift. The method is two lines:
+
+   ```python
+   def list_widgets(self, org_id: str, *, page: int | None = None) -> dict[str, Any]:
+       kwargs = list_widgets._get_kwargs(org_id, **{"page": page} if page else {})
+       return self._read_or_raise(self._request_with_retry(**kwargs), "list_widgets")
+   ```
+
+   - Build from `_get_kwargs`, not `sync_detailed`: the generated
+     `_parse_response` calls `from_dict` on an error body unguarded, so an
+     undeclared one raises before the facade sees the status. Omit unset
+     parameters rather than passing `None` — the builder renders some before it
+     filters `None` out. Both are private to the generator, so pin them in
+     `tests/test_compat.py`.
+   - Send through `_request_with_retry`, and read through `_read_or_raise`,
+     which checks the status first.
+   - Return `dict[str, Any]`. The generated models are exported for callers who
+     want typing; a hand-written `TypedDict` would not survive regeneration.
+   - A new error type subclasses `UnstractError`.
+
+   `PlatformKeyClient.whoami` is the smallest example in the tree.
+
 6. **Run the tests:** `uv run pytest tests/`. `tests/test_compat.py` compares
    this client against the last released one, vendored under `tests/baseline/`.
    Refresh that baseline only when you mean to move the parity reference point,
@@ -87,8 +112,10 @@ fail the same way. If it is red, run step 3 and commit the result.
 
 Choose the bump by what changed for callers: **major** when the spec removed or
 renamed something callers depend on, **minor** for new endpoints or new
-behaviour, **patch** for fixes that keep the surface identical. A generated diff
-with removals in it is the signal for major — spec upgrades produce those.
+behaviour — a new facade method included — **patch** for fixes that keep the
+surface identical. A generated diff with removals in it is the signal for major
+— spec upgrades produce those. Behaviour the baseline pinned that has moved goes
+in `ACCEPTED_DIVERGENCES` in the same commit.
 
 Do not touch `__version__` in `src/unstract/api_deployments/__init__.py` in your
 PR. The in-repo value is the *last released* version; `main.yml` reads it,

README.md

@@ -113,12 +113,30 @@ client = APIDeploymentsClient(
 The retry logic uses exponential backoff with full jitter and respects the `Retry-After` header on 429 responses.
 
 
+## Errors
+
+Every error either client raises derives from `UnstractError`:
+
+| Exception | Raised by |
+|-----------|-----------|
+| `UnstractError` | base of both — catch this to catch everything |
+| `APIDeploymentError` | `APIDeploymentsClient` |
+| `PlatformClientError` | `PlatformKeyClient` |
+
+`APIDeploymentsClientException` is an alias of `UnstractError`, so existing
+`except` clauses keep working.
+
+Transport failures are raised as the `requests` exception types
+(`ConnectionError`, `Timeout`, and friends) rather than the httpx ones.
+
 ## Internals
 
 `unstract.api_deployments._sdk_docstudio` is generated from the deployment API's
 OpenAPI spec by `tools/gen_sdk.sh` and is an implementation detail of the
-transport. `APIDeploymentsClient` is the supported surface — import from it, not
-from the generated tree, which is regenerated wholesale whenever the spec moves.
+transport. `APIDeploymentsClient` and `PlatformKeyClient` are the supported
+surface — import from those, or from the response models re-exported alongside
+them, not from the generated tree, which is regenerated wholesale whenever the
+spec moves.
 
 ## Cloning an organization
 

src/unstract/api_deployments/__init__.py

@@ -1,7 +1,22 @@
 __version__ = "1.6.0"
 
+from ._sdk_docstudio.models import (
+    APIDeploymentSummary as APIDeploymentSummary,
+)
+from ._sdk_docstudio.models import (
+    PaginatedAPIDeploymentSummaryList as PaginatedAPIDeploymentSummaryList,
+)
+from ._sdk_docstudio.models import (
+    WhoAmIResponse as WhoAmIResponse,
+)
+from .client import APIDeploymentError as APIDeploymentError
 from .client import APIDeploymentsClient as APIDeploymentsClient
-from .client import PlatformAPIClient as PlatformAPIClient
+from .client import (
+    APIDeploymentsClientException as APIDeploymentsClientException,
+)
+from .client import PlatformClientError as PlatformClientError
+from .client import PlatformKeyClient as PlatformKeyClient
+from .client import UnstractError as UnstractError
 
 
 def get_sdk_version():