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.

Two real 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.
- `_send` resolves the transport inside the translated region. A client
  closed by another thread mid-flight raised httpx's own `RuntimeError`,
  which is outside the translated subtree and reached the caller untranslated.

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.
- An empty `org_id` 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 becomes a recipe: which class
  a new operation belongs to, the method shape, why it builds from
  `_get_kwargs` rather than `sync_detailed`, and the rule that a new error
  type subclasses `UnstractError`.

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,45 @@ 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.
 
+   **Which class does it belong to?** A deployment key and a deployment URL mean
+   `APIDeploymentsClient`; a platform key means `PlatformKeyClient`. Anything
+   else is a new subclass of `_HttpxFacade`, never a free-standing class — the
+   base owns the pooled transport, the retry policy and the translation of httpx
+   failures into the `requests` types callers catch, and a class that reimplements
+   those will drift from the one that does not.
+
+   **The shape of a facade method**, which is all a new operation should need:
+
+   ```python
+   def list_widgets(self, org_id: str, *, page: int | None = None) -> dict[str, Any]:
+       """One sentence, then Args and Returns."""
+       kwargs = list_widgets._get_kwargs(org_id, page=page)
+       return self._read_or_raise(self._request_with_retry(**kwargs), "list_widgets")
+   ```
+
+   Four rules behind it:
+
+   - **Build from `_get_kwargs`, not from `sync_detailed`.** The generated
+     `_parse_response` calls `from_dict` on a declared error status with no
+     guard, so a gateway answering 401 with HTML, or DRF answering
+     `{"detail": ...}`, raises `JSONDecodeError` or `KeyError` before the facade
+     sees the status. `_get_kwargs` is private to the generator, so pin its shape
+     in `tests/test_compat.py` — a generator bump then fails there rather than at
+     a customer's call.
+   - **Send through `_request_with_retry`**, so the operation gets the retry
+     policy and `Retry-After` handling the README already promises.
+   - **Check the status before reading the body**, via `_read_or_raise`. Never
+     `from_dict` a body the server was not obliged to send.
+   - **Return `dict[str, Any]`.** The generated models are exported for callers
+     who want typing; do not hand-write a `TypedDict` mirroring the spec, because
+     regeneration will not update it.
+
+   **A new error type** subclasses `UnstractError`, never `Exception` directly —
+   `APIDeploymentsClientException` is an alias of that base, and callers catching
+   it must keep catching everything.
+
+   `PlatformKeyClient.whoami` is the smallest worked 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,7 +126,11 @@ 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
+behaviour — including an operation reached only through a new facade method —
+**patch** for fixes that keep the surface identical. If behaviour the baseline
+pinned has moved, name the divergence in `ACCEPTED_DIVERGENCES` and in the
+`tests/test_compat.py` module docstring in the same commit; a divergence pinned
+by a test but missing from that list is only findable by reading all of them. A generated diff
 with removals in it is the signal for major — spec upgrades produce those.
 
 Do not touch `__version__` in `src/unstract/api_deployments/__init__.py` in your

README.md

@@ -113,12 +113,65 @@ client = APIDeploymentsClient(
 The retry logic uses exponential backoff with full jitter and respects the `Retry-After` header on 429 responses.
 
 
+## Reading an account with a platform key
+
+`PlatformKeyClient` takes a **platform** API key rather than a deployment key,
+and answers what that key can see. A platform key cannot run a deployment, and a
+deployment key cannot describe the account, so the two clients are not
+interchangeable.
+
+```python
+from unstract.api_deployments import PlatformKeyClient
+
+with PlatformKeyClient("https://us-central.unstract.com", "your_platform_key") as pkc:
+    identity = pkc.whoami()
+    page = pkc.list_deployments(identity["organization_id"], page_size=50)
+    for deployment in page["results"]:
+        print(deployment["api_name"], deployment["api_endpoint"])
+```
+
+`api_key` falls back to `$UNSTRACT_PLATFORM_KEY`. `whoami()` resolves the
+`organization_id` every other operation needs, so it takes no organisation
+argument. `list_deployments()` is paginated — follow `next` rather than assuming
+`results` is the whole set. Retries, TLS and timeout settings are the same
+parameters, with the same defaults, as `APIDeploymentsClient`.
+
+Both methods return plain dicts. To have them typed, hand the result to the
+generated model for that shape:
+
+```python
+from unstract.api_deployments import WhoAmIResponse
+
+identity = WhoAmIResponse.from_dict(pkc.whoami())
+```
+
+## 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 the name this exception shipped under and
+remains an alias of `UnstractError`, so existing `except` clauses keep working
+unchanged.
+
+Transport failures are raised as the `requests` exception types
+(`ConnectionError`, `Timeout`, and friends) rather than the underlying httpx
+ones, so callers written against earlier releases catch them by the same names.
+
 ## 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, not from the generated tree, which is regenerated
+wholesale whenever the spec moves. The response models re-exported from
+`unstract.api_deployments` are generated from the same spec and are safe to
+import.
 
 ## 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():