feat(sdk): providerKeys on environments, connector credential type and codes

[parnexcodes]

Closes #27

What

• New client.environments resource: list(organization_id), get(ref, organization_id=...), update(ref, ..., provider_keys=...) with an Environment dataclass (provider_keys, is_default, current_version, secrets_access, egress_allow, raw).
• provider_keys "gateway" (default) or "plain", documented on the dataclass and update. egress_allow=None clears the allowlist (UNSET keeps it).
• credential_type on Connector (oauth | personal_token | bot_token | org_token | user_token | token | None).
• ConnectorTokenInvalidError (connector_token_invalid, 400) and ConnectorUnreachableError (connector_unreachable, 502), exported from usedock.
• README: one short Environments section and the two codes in the error list.

Why

usedock/dock#106 added providerKeys to environments and dock#86 the connector credential type; the SDK had no environments surface, so the setting could not be read or changed. The two connector codes had no typed errors.

How to verify

ruff check . && ruff format --check . && mypy && pytest. New tests cover environment list/get/update (sending and reading provider_keys, egress null), credential_type, and the two typed errors. Shared scenarios pass against usedock/dock main (fac9293); SCENARIOS_REF is unchanged because only a fixture changed since the pin.

Risk

Additive only. Environment.provider_keys defaults to "gateway" when the field is absent (older servers).

🤖 Generated with Claude Code

[parnexcodes]

Review: feat(sdk): providerKeys on environments, connector credential type and codes (dock-python)

Verdict: SHIP (after fix dda2beb)

Blocking (fixed in dda2beb)

1. src/usedock/models.py Environment dropped safeForThirdParties, passGithub, passSecrets, passDockCredentials, passAgentsCredentials, varNames, createdAt and updatedAt, which the JS and Go types expose. Failure: after update(pass_github=False) a Python caller had no typed way to read the posture back, only .raw. Fix: added the fields. Tests: test_environment_reads_posture_fields and test_environments_update_sends_posture_and_egress_list.
2. The update docstring and README said only provider_keys="plain" needs an admin. The API requires an admin for every update. Corrected, and the version semantics are now documented.

Verified against usedock/dock main

• Routes: GET /v1/environments?organizationId= (required uuid), GET and PATCH /v1/environments/:ref with optional organizationId for name refs (environments.controller.ts). These are public, documented routes (documentation/content/docs/api/environments.mdx).
• UpdateEnvironmentDto accepts exactly name, isDefault, secretsAccess, safeForThirdParties, passGithub, passSecrets, passDockCredentials, passAgentsCredentials, providerKeys, egressAllow (nullable). All three SDKs now expose that same set.
• Roles: getByRef/listByOrg need a member; update calls resolveRef(..., 'admin'), so every PATCH needs an admin, not only providerKeys: plain. Docs in all three SDKs now say this.
• Versions: only posture fields (pass flags, safeForThirdParties, providerKeys, egressAllow) go through bumpVersion. name, isDefault and secretsAccess update the environment row without a new version. This is now documented that way.
• toView returns varNames, file {path,size}, repos and connection status, never values. The SDK types carry no secret values.
• connector_token_invalid 400 and connector_unreachable 502 come from connectors/connector-verify.ts. credentialType values match CONNECTOR_CREDENTIAL_TYPES and are null when not connected.
• Additive only (new resource, new optional fields, new codes), so this is a semver minor.

Non-blocking (outside these PRs)

1. documentation/content/docs/api/environments.mdx (usedock/dock): the PATCH field table leaves out providerKeys. It is covered in concepts/model-keys/threat-model but not in the API reference. This belongs in a follow-up on the dock repo.

Checks

• ruff check .: pass
• ruff format --check .: pass
• mypy: pass
• pytest (DOCK_SCENARIOS_DIR at pinned ref): 114 passed, 9 skipped (live)
• CI on dda2beb: all green