feat: pick up the whoami and deployment-listing operations

[praveen-formido]

What

Runs the spec-upgrade pipeline against Zipstack/unstract main at 520b98d7a, picking up the two operations the CLI needs:

operation	path	credential
whoami	/api/v1/unstract/whoami/	platform key
list_deployments	/api/v1/unstract/{org_id}/api/deployment/	platform key

From Zipstack/unstract#2269 and Zipstack/unstract#2278.

Why

unstract-cli currently reaches into unstract.clone.PlatformClient — the org-cloning tool's hand-written admin client — to do org discovery and deployment listing, because neither operation existed on the generated surface. That is how the CLI drifted off the spec pipeline: its vendored docstudio.json is still from 0c5f36dab, and tests/test_contract.py is structurally blind to commands that don't derive from a spec.

This makes both operations reachable from the SDK, so the CLI can drop its CLIPlatformClient subclass and a customer can do the same work from either surface.

How

Steps 1–2 — spec and provenance move together. Copied byte-for-byte; SPEC_SOURCE gains the new revision and sha256 in this same commit. I verified the previous record first — the vendored file matched its recorded sha256 and was byte-identical to the backend at eddd4b746 — so this starts from an honest baseline rather than assuming one.

Steps 3–4 — regeneration is purely additive. Reviewed with git add -N so newly created files were visible:

• new api/identity/whoami.py, new api/deployment/list_deployments.py
• six new models (WhoAmIResponse, PlatformKeyError, ApiKeyPermission, APIDeploymentSummary, PaginatedAPIDeploymentSummaryList, and a run-statuses item)
• execute.py / status.py changed — prose only, where #2278 reworded descriptions. I filtered the diff to non-docstring lines to confirm nothing functional moved.

No operation, field or model removed ⇒ minor, not major. The generator exited clean, and a second regeneration is byte-identical, so sdk-drift will pass.

Step 5 — PlatformAPIClient, a sibling rather than an extension. APIDeploymentsClient takes a deployment URL and derives org + api_name from its last two segments; whoami has neither, and both new operations take a platform key rather than a deployment key. So the new class shares the generated transport (both schemes are HTTP bearer — only the token differs) and the same exception type, but owns its own construction. Folding them together would have meant a class whose required api_url is meaningless for half its methods.

Step 6 — 438 tests pass, up from 419. __version__ and the compat baseline are deliberately untouched, per the skill: the release workflow reads the former as the last released version and bumps at dispatch, and a spec upgrade is not a reason to move the parity reference point.

Review round: six findings, all fixed in 3e9717e

A /code-review pass at medium effort found six issues in the first commit's facade. Worth recording that the same review at low effort reported the PR clean — the medium pass is what surfaced these.

#	Fix
1–2	The body is read as JSON, not through the generated model. sync_detailed reaches _parse_response, which does PlatformKeyError.from_dict(response.json()) on a 401 with no guard: a gateway answering 401 with HTML raises JSONDecodeError, a DRF-shaped {"detail": …} raises KeyError: 'message' — both before the facade sees the response. Now built from the generated _get_kwargs and read via APIDeploymentsClient._read_body, which is why that helper exists
3	Requests go through _send, so transport failures arrive as the requests types the module docstring promises, rather than raw httpx.ConnectError
4	close() / __enter__ / __exit__ — pooled connections had nothing to release them
5	Auth header set per request; AuthenticatedClient bakes its own on first use, so a reassigned api_key was silently ignored
6	Re-exported from the package root

Findings 1–2 are the same defect class as the one below: the first commit fixed the half where reporting a refusal crashed, and missed the half where building the model crashed first.

Five mutations killed to confirm the fixes are pinned: unguarded response.json(), dropping the transport translation, capturing the key with the transport, neutering close, and removing the re-export.

A defect the first commit's tests caught

_error_text fell back to response.text, but the generated Response is an attrs wrapper carrying .content, and parsed is a model instance rather than a mapping. A 401 through the new client would have raised AttributeError while trying to report the refusal — a crash instead of "your key was rejected". Both halves are fixed; the _error_text change is additive (getattr(response, "text", None), then decode .content), so httpx callers behave identically.

Two decisions I'd like a second opinion on

1. The class name. PlatformClient is already taken by unstract.clone, and two classes of that name shipping in one distribution seemed worse than a slightly longer one. PlatformAPIClient is my choice, not a considered team convention — easy to rename before release.

2. The test manifest shape. test_every_declared_operation_is_wrapped fired exactly as designed when the spec grew. Extending WRAPPED_OPERATIONS to four was not viable, though:

• whoami declares no ErrorResponse, so that suite's assert set(errors.values()) > {"ErrorResponse"} is false for it by construction;
• _declared_responses indexes content unconditionally, and both new operations declare a bodyless 500, which would KeyError.

So there is a parallel PLATFORM_OPERATIONS manifest with its own status pins and error-reporting coverage, and the whole-set comparison unions the two — preserving the property that test exists for (an operation belonging to neither still fails) without forcing platform operations through assertions that are untrue for them. If you'd rather the two families converge, that's a bigger change to the existing assertions and I'd want your call first.

Can this PR break any existing features

No. APIDeploymentsClient is untouched apart from the additive _error_text fallback (its _read_body is now also reused by the new class); execute and status changed only in docstrings. The 419 pre-existing tests all still pass.

Notes on Testing

438 passing. New coverage: both operations' declared error statuses reported with their reason, the four whoami fields, the org segment and query params reaching list_deployments, the paginated envelope read back, key-from-environment fallback, and refusals at construction for a missing key or a hostless base URL. Patched at AuthenticatedClient.get_httpx_client rather than above sync_detailed, so the generated parsing and model construction are genuinely exercised — that is the layer a regeneration changes.

Pre-existing lint debt in src/unstract/clone/** and tests/clone/** is untouched and unrelated.

Next

Not in this PR: a minor release to PyPI, then bump-client-pins in unstract-cli and deleting CLIPlatformClient.

🤖 Generated with Claude Code

https://claude.ai/code/session_01Y7U4ggFchu91zKYcRxFRNZ

[greptile-apps]

via Greptile

Confidence Score: 5/5

The PR appears safe to merge; the previously reported generated-parser coverage gap is resolved and no new actionable defect remains.

Summary

• Adds generated whoami and paginated deployment-listing endpoints and response models.
• Introduces PlatformKeyClient with retries, transport error translation, connection lifecycle management, and environment-based credential fallback.
• Refactors deployment and platform clients onto a shared transport facade.
• Adds package-level exports, usage documentation, and compatibility coverage for generated parsing, request construction, errors, retries, and concurrency.

Diagram

%%{init: {'theme': 'neutral'}}%%
flowchart LR
    Caller --> PKC[PlatformKeyClient]
    PKC --> Shared[_HttpxFacade]
    Shared --> WhoAmI[GET /api/v1/unstract/whoami/]
    WhoAmI --> Org[organization_id]
    Org --> Listing[GET /api/v1/unstract/org_id/api/deployment/]
    Listing --> Page[Paginated deployment results]
    Caller --> ADC[APIDeploymentsClient]
    ADC --> Shared
    Shared --> Transport[Authenticated httpx transport]

Loading

_{Reviews (3) · Last reviewed commit: "refactor: fold the platform client into ..."}