[parnexcodes]

Closes #17

What

• client.docks.create(connectors=[...]) and DockInfo.connectors.
• client.connectors.list(workspace_id), .connect(workspace_id, kind, token), .disconnect(workspace_id, kind), returning Connector, Connector and ConnectorState.
• client.images.list() returning Image (name, description, arch, size_mib, contents, available).
• ConnectorNotConnectedError, ConnectorAdminOnlyError, ImageUnknownError, ImageUnavailableError, all subclasses of DockError (existing except DockError and .code keep working).
• SCENARIOS_REF bumped to 05d0182f83f3f7675567cc812c7801659f9cd3b6; the scenario runner maps images.list and connectors.*, and the fake server accepts PUT.
• README section and error docs.

Why

usedock/dock shipped connectors and the Dockyard catalog; the SDK had no way to use them. Refs usedock/dock#59.

How to verify

pip install -e ".[dev]"
DOCK_SCENARIOS_DIR=<dock@05d0182>/sdk-scenarios DOCK_SCENARIOS_REQUIRED=1 pytest tests
ruff check . && ruff format --check . && mypy

Local results: 91 passed, 9 skipped (live scenarios, need a real API); ruff, ruff format and mypy clean. The offline list-connectors and list-images scenarios pass. New unit tests cover request shape, models and typed errors.

Risk

Low and additive. Error classes subclass DockError, so existing handling is unchanged. connectors.oauthStart is intentionally not exposed. branch does not take connectors (the API op does not list it).

🤖 Generated with Claude Code

[parnexcodes]

Review: feat(sdk): connectors on create, connectors and images lists (dock-python#18)

Verdict: SHIP

Reviewed together with usedock/dock-js#13, #18 and usedock/dock-go#14, against usedock/dock 05d0182 (connectors controller/service/verify, images controller/service, dock-view allowlist, create/branch DTOs, sdk-scenarios ops.yaml and the list-connectors / list-images scenarios).

Verified against the API:

• Paths and methods match connectors.controller.ts and images.controller.ts: GET /v1/workspaces/{id}/connectors, PUT/DELETE /v1/workspaces/{id}/connectors/{kind} with body {token}, GET /v1/images. Workspace id and kind are path-escaped in all three SDKs.
• Disconnect returns {kind, status: 'not_connected'}; connect returns the connector view. Field mapping is right (sizeMiB maps to sizeMiB / size_mib / SizeMiB; accountLabel, oauthAvailable, readOnly, updatedAt).
• connectors is in the dockView allowlist and on CreateDockDto. BranchDockDto does not accept it (a branch inherits the source's connectors), and none of the SDKs add it to branch, which is correct.
• The token is only sent in the PUT body. It is never in a path, a repr, a log line, or an error message, and the server never echoes it back.
• The changes only add things: new services, optional fields and new error types or constants. That makes this a minor release.
• Cross-language: the same nouns and verbs in all three (connectors.list/connect/disconnect, images.list, connectors on create and on the Dock object). oauthStart is in ops.yaml, but it is a browser redirect flow, and no SDK exposes it. That is consistent and fine.
• Error codes: JS exported connector_not_found (404 on disconnect of a kind that is not connected) but Python and Go did not. I aligned them: Python ConnectorNotFoundError, Go CodeConnectorNotFound, each with a test.

Blocking

None.

Fixed in this review (35d21d0)

1. src/usedock/errors.py: there was no typed error for connector_not_found. Disconnecting a kind that is not connected raised a plain DockError, while JS and Go name the code. I added ConnectorNotFoundError, exported it, and added test_disconnect_not_connected_raises_connector_not_found.
2. README.md and the ConnectorAdminOnlyError docstring said "workspace admins". The API checks the organization admin role, and members who connect get forbidden, not connector_admin_only. I corrected the wording.

Non-blocking

1. DockInfo gained connectors before raw. Anyone who builds DockInfo(...) positionally all the way to raw would break, but these are response models and that use is unlikely.
2. connect can also fail with connector_token_invalid (400) and connector_unreachable (502). None of the three SDKs type these codes, so the SDKs stay consistent. Adding them is a possible follow-up across all three.

Checks

• ruff check . / ruff format --check .: pass
• mypy: pass
• pytest (scenarios at 05d0182): 91 passed / 9 skipped (live and CI only)
• CI on 35d21d0: test (3.9, 3.13), gitleaks and cla all green