keboola-cli 0.63.4__py3-none-any.whl

keboola_agent_cli/data_science_client.py

@@ -0,0 +1,342 @@
+"""Keboola Data Science API client (data-app deployment records).
+
+The Data Science API owns the *deployment* side of a data app — id, state,
+desiredState, url, configVersion. The Storage API
+(``keboola.data-apps`` configs) owns the *configuration* side — git block,
+encrypted secrets, slug, runtime size. Both must stay in sync; see
+``services/data_app_service.py`` for the orchestration.
+
+URL derivation: ``https://data-science.<stack-suffix>`` from the project's
+connection URL via ``BaseHttpClient._derive_service_url``. Auth: same
+``X-StorageApi-Token`` as the Storage API. The single exception is
+``GET /apps/{id}/password`` which additionally requires
+``X-KBC-ManageApiToken`` -- the manage token is passed per-call so the
+client itself stays project-scoped.
+
+Verified shapes (writeup §2 / §6 / §9, replayed in this PR's live
+validation):
+
+    POST   /apps                          -> 201, {id, configId, ...}
+    GET    /apps                          -> 200, [{id, configId, state, desiredState, url}, ...]
+    GET    /apps/{id}                     -> 200, full deployment record
+    PATCH  /apps/{id}                     -> 200, deployment record (only
+                                              desiredState / configVersion /
+                                              restartIfRunning persist;
+                                              ``config:{...}`` is silently
+                                              dropped)
+    DELETE /apps/{id}                     -> 202, cascades to Storage config
+    GET    /apps/{id}/password            -> 200, {password: "<20 hex>"}
+                                              (requires both Storage and
+                                              Manage tokens)
+    GET    /apps/{id}/logs/tail           -> 200, text/plain container log
+                                              tail. ``lines=N`` and
+                                              ``since=ISO8601`` are mutually
+                                              exclusive on the server.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+from typing import Any
+from urllib.parse import quote
+
+from .constants import DEFAULT_TIMEOUT
+from .http_base import BaseHttpClient
+
+logger = logging.getLogger(__name__)
+
+
+class DataScienceClient(BaseHttpClient):
+    """HTTP client for the Keboola Data Science API (``/apps``).
+
+    Inherits retry / backoff / token-masking from ``BaseHttpClient``.
+    """
+
+    def __init__(self, stack_url: str, token: str) -> None:
+        self._stack_url = stack_url.rstrip("/")
+        ds_base_url = self._derive_service_url(self._stack_url, "data-science")
+        headers = {
+            "X-StorageApi-Token": token,
+        }
+        super().__init__(
+            base_url=ds_base_url,
+            token=token,
+            headers=headers,
+            timeout=DEFAULT_TIMEOUT,
+        )
+
+    def __enter__(self) -> DataScienceClient:
+        return self
+
+    def __exit__(self, *args: Any) -> None:
+        self.close()
+
+    def list_apps(self) -> list[dict[str, Any]]:
+        """Return the thin index of data apps in the project (no body filter).
+
+        The Data Science API scopes responses by the token's project; there
+        is no ``branchId`` query parameter on the list endpoint.
+        """
+        response = self._do_request("GET", "/apps")
+        body = response.json()
+        # Some stacks wrap the list in {"data": [...]}; fall back gracefully.
+        apps = (body.get("data") or body.get("apps") or []) if isinstance(body, dict) else body
+        return apps if isinstance(apps, list) else []
+
+    def get_app(self, app_id: str) -> dict[str, Any]:
+        """Fetch a single deployment record by numeric app id."""
+        response = self._do_request("GET", f"/apps/{quote(str(app_id), safe='')}")
+        return response.json()
+
+    def create_app(
+        self,
+        *,
+        type_: str,
+        name: str,
+        description: str,
+        config: dict[str, Any],
+        branch_id: int | None = None,
+    ) -> dict[str, Any]:
+        """Create the deployment shell + linked Storage config in one call.
+
+        Server-generated identifiers: ``id`` (numeric) and ``configId``
+        (ULID). The ``configId`` field in the request body is silently
+        ignored (writeup §5) -- callers must accept whatever ULID the
+        server assigns and round-trip it on subsequent updates.
+
+        ``config`` carries the *initial* Storage configuration body. The
+        full config (git block, encrypted secrets, etc.) is added via
+        ``KeboolaClient.update_config`` after creation; sending it here is
+        possible but the encryption step depends on knowing
+        ``config_id`` first, so the canonical flow is:
+        ``create_app`` -> encrypt secrets -> ``update_config``.
+        """
+        payload: dict[str, Any] = {
+            "branchId": branch_id,
+            "type": type_,
+            "name": name,
+            "description": description,
+            "config": config,
+        }
+        response = self._do_request(
+            "POST",
+            "/apps",
+            content=json.dumps(payload).encode("utf-8"),
+            headers={"Content-Type": "application/json"},
+        )
+        return response.json()
+
+    def patch_app(
+        self,
+        app_id: str,
+        *,
+        desired_state: str | None = None,
+        config_version: str | None = None,
+        restart_if_running: bool | None = None,
+    ) -> dict[str, Any]:
+        """Update the deployment record (state / pinned config version).
+
+        IMPORTANT: never sends a ``config`` block — that surface is owned
+        by the Storage API (writeup §2.1, §8 pitfall row 3). Updating
+        size / autoSuspend / git settings goes through ``update_config``
+        on the Storage API.
+
+        The §9 redeploy contract requires
+        ``desired_state="running"`` + ``config_version=<N>``
+        + ``restart_if_running=True`` together when bumping the deployed
+        config version; sending ``config_version`` alone yields HTTP 422.
+        """
+        payload: dict[str, Any] = {}
+        if desired_state is not None:
+            payload["desiredState"] = desired_state
+        if config_version is not None:
+            payload["configVersion"] = config_version
+        if restart_if_running is not None:
+            payload["restartIfRunning"] = restart_if_running
+        response = self._do_request(
+            "PATCH",
+            f"/apps/{quote(str(app_id), safe='')}",
+            content=json.dumps(payload).encode("utf-8"),
+            headers={"Content-Type": "application/json"},
+        )
+        return response.json()
+
+    def delete_app(self, app_id: str) -> None:
+        """Delete the deployment AND the linked Storage config (cascade).
+
+        Returns HTTP 202 on success; the body is empty.
+        """
+        self._do_request("DELETE", f"/apps/{quote(str(app_id), safe='')}")
+
+    def get_app_password(self, app_id: str, manage_token: str) -> dict[str, Any]:
+        """Retrieve the auto-generated simpleAuth password.
+
+        Requires both the project's Storage token (already on
+        ``self._client``) AND a Manage API token, supplied per-call so the
+        manage token never lives on the client instance.
+
+        The 20-character hex password is auto-generated at app create time
+        and is NOT rotatable -- to change it you must delete and recreate
+        the app (writeup §11.2).
+        """
+        path = f"/apps/{quote(str(app_id), safe='')}/password"
+        # Pass the Manage token via per-request `headers=`. httpx merges these
+        # with the client's persistent headers for this call only, so the
+        # manage token never lives on `self._client`. Using `_do_request`
+        # gives us the same retry/backoff and uniform error mapping as every
+        # other call in this client (no bespoke try/except needed).
+        response = self._do_request(
+            "GET",
+            path,
+            headers={"X-KBC-ManageApiToken": manage_token},
+        )
+        return response.json()
+
+    def tail_app_logs(
+        self,
+        app_id: str,
+        *,
+        lines: int | None = None,
+        since: str | None = None,
+    ) -> str:
+        """Fetch the container log tail from ``/apps/{id}/logs/tail``.
+
+        Returns the response body verbatim as plain text (``text/plain``)
+        -- one log line per ``\\n``, trailing newline preserved as the
+        server sent it. Callers that want a list of lines should call
+        ``text.splitlines()``.
+
+        ``lines`` and ``since`` are mutually exclusive on the server
+        (400 ``Only one of "since" or "lines" can be set``); the caller
+        MUST enforce that constraint before invoking. Passing neither
+        returns the full current container buffer. ``lines=0`` and
+        negative values are rejected by the server with a 400 -- callers
+        opting into the full buffer should pass ``lines=None``.
+
+        ``since`` must be an ISO 8601 timestamp WITH timezone (``Z`` or
+        ``+00:00``); naive datetimes and date-only values are rejected
+        by the server with a 400.
+        """
+        path = f"/apps/{quote(str(app_id), safe='')}/logs/tail"
+        params: dict[str, Any] = {}
+        if lines is not None:
+            params["lines"] = lines
+        if since is not None:
+            params["since"] = since
+        # ``params or None`` keeps the URL clean (no trailing ``?``) when
+        # the caller wants the server's default buffer-all behavior.
+        response = self._do_request("GET", path, params=params or None)
+        return response.text
+
+    # ------------------------------------------------------------------
+    # Git repository (sandboxes-service /apps/{id}/git-repo/*)
+    #
+    # These endpoints introspect and manage the git repository a data app
+    # is deployed from. Ground truth: keboola/sandboxes-service server
+    # source + docs/swagger.yaml. Two functional groups:
+    #
+    #   * Repo introspection (git-repo, /branches, /entrypoints) -- works
+    #     for ANY configured repo (managed or external); auth = the same
+    #     X-StorageApi-Token, permission CanManageApp.
+    #   * Credential management (/credentials GET + POST) -- ONLY for a
+    #     *managed* git repo (app.managedGitRepoId set); a repo configured
+    #     via `data-app create --git-repo <url>` is *external*, so these
+    #     return 409. Auth needs an admin storage token
+    #     (CanManageAppRepoCredentials).
+    #
+    # IMPORTANT response-shape gotchas (verified in both sources):
+    #   * /branches returns a RAW top-level JSON array (NOT wrapped in
+    #     {branches: [...]}).
+    #   * /entrypoints returns a RAW top-level array<string>.
+    #   * /credentials (GET) IS wrapped: {"credentials": [...]}.
+    #   * POST /credentials returns the created credential; the one-time
+    #     ``secret`` is present ONLY for type=http_token and ONLY here.
+    # ------------------------------------------------------------------
+
+    def get_git_repo(self, app_id: str) -> dict[str, Any]:
+        """Return the clone URLs of the app's configured git repository.
+
+        Shape: ``{"sshUrl": str|None, "httpsUrl": str|None,
+        "isManagedGitRepo": bool}``. For external repos only the URL
+        matching the configured protocol is populated (the other is
+        ``None``) and embedded credentials are stripped. ``409`` if the
+        app has no git repository configured.
+        """
+        response = self._do_request("GET", f"/apps/{quote(str(app_id), safe='')}/git-repo")
+        body = response.json()
+        return body if isinstance(body, dict) else {}
+
+    def list_git_branches(self, app_id: str) -> list[dict[str, Any]]:
+        """List the remote branches of the app's configured git repository.
+
+        Returns the server's RAW top-level array of branch objects
+        ``[{"branch", "comment", "sha", "author": {"name", "email"},
+        "date"}]`` (HEAD/origin/HEAD filtered, sorted by name). Works for
+        managed and external repos alike.
+        """
+        response = self._do_request("GET", f"/apps/{quote(str(app_id), safe='')}/git-repo/branches")
+        body = response.json()
+        return body if isinstance(body, list) else []
+
+    def list_git_entrypoints(self, app_id: str) -> list[str]:
+        """List root-level ``.py`` entrypoint files of the app's repo.
+
+        Returns the server's RAW top-level ``array<string>`` of root
+        filenames on the configured branch (or the repo default).
+        Extension is hardcoded to ``py`` server-side, so non-Python
+        entrypoints are not listable here.
+        """
+        response = self._do_request(
+            "GET", f"/apps/{quote(str(app_id), safe='')}/git-repo/entrypoints"
+        )
+        body = response.json()
+        return [str(item) for item in body] if isinstance(body, list) else []
+
+    def list_git_credentials(self, app_id: str) -> dict[str, Any]:
+        """List the credentials of the app's MANAGED git repository.
+
+        Shape: ``{"credentials": [{"id", "type", "name", "permissions",
+        "ownerAdminId", "createdAt"}]}``. The ``secret`` is NEVER returned
+        here. ``409`` if the app has no managed git repository; requires an
+        admin storage token.
+        """
+        response = self._do_request(
+            "GET", f"/apps/{quote(str(app_id), safe='')}/git-repo/credentials"
+        )
+        body = response.json()
+        return body if isinstance(body, dict) else {}
+
+    def create_git_credential(
+        self,
+        app_id: str,
+        *,
+        type_: str,
+        permissions: str,
+        public_key: str | None = None,
+        name: str | None = None,
+    ) -> dict[str, Any]:
+        """Create a credential for the app's MANAGED git repository.
+
+        ``type_`` is ``"ssh_key"`` or ``"http_token"``; ``permissions`` is
+        ``"readOnly"`` or ``"readWrite"``. ``public_key`` is required IFF
+        ``type_ == "ssh_key"`` and MUST be absent otherwise (the server
+        returns 400 on a wrong combination).
+
+        Returns the created credential. The one-time ``secret`` field is
+        present ONLY when ``type_ == "http_token"`` and is never retrievable
+        again. ``409`` if the app has no managed git repository; requires an
+        admin storage token.
+        """
+        payload: dict[str, Any] = {"type": type_, "permissions": permissions}
+        if public_key is not None:
+            payload["publicKey"] = public_key
+        if name is not None:
+            payload["name"] = name
+        response = self._do_request(
+            "POST",
+            f"/apps/{quote(str(app_id), safe='')}/git-repo/credentials",
+            content=json.dumps(payload).encode("utf-8"),
+            headers={"Content-Type": "application/json"},
+        )
+        return response.json()

keboola_agent_cli/dev_portal_client.py

@@ -0,0 +1,323 @@
+"""Keboola Developer Portal HTTP client (apps-api.keboola.com).
+
+Auth model:
+- Login (email + password) returns a bearer token. On a personal account, the
+  first login returns an MFA session; we prompt the user via /dev/tty and
+  re-login with {email, session, code} to obtain the bearer.
+- The bearer lives ONLY on this client instance (in self._bearer). It is
+  never written to disk, never logged, and discarded when the client closes.
+- Each kbagent invocation logs in fresh; there is no token cache.
+
+The client is intentionally dumb: dry-run, diff, and confirm logic belong to
+the service and command layers.
+"""
+
+from __future__ import annotations
+
+import logging
+import urllib.error
+import urllib.request
+from typing import Any
+
+import httpx
+
+from .constants import DP_MFA_CHALLENGE_TYPE, MAX_API_ERROR_LENGTH
+from .errors import ErrorCode, KeboolaApiError
+from .http_base import BaseHttpClient
+from .models import DeveloperPortalIdentity
+
+logger = logging.getLogger(__name__)
+
+
+def _tty_prompt(label: str, *, secret: bool = False) -> str | None:
+    """Prompt via the controlling terminal so a redirected stdin can't break it.
+
+    Returns None when no /dev/tty is available (non-interactive shell, no
+    controlling terminal). Caller must treat None as "cannot prompt".
+    """
+    try:
+        with open("/dev/tty", "w") as out:
+            if secret:
+                import getpass
+
+                return getpass.getpass(label, stream=out)
+            out.write(label)
+            out.flush()
+            with open("/dev/tty") as tin:
+                return tin.readline().rstrip("\n")
+    except OSError:
+        return None
+
+
+class DeveloperPortalClient(BaseHttpClient):
+    """HTTP client for the Keboola Developer Portal."""
+
+    def __init__(self, identity: DeveloperPortalIdentity) -> None:
+        # We don't have a bearer yet — pass empty token. Login populates it.
+        super().__init__(
+            base_url=identity.portal_url,
+            token="",
+            headers={"Accept": "application/json"},
+        )
+        self._identity = identity
+        self._bearer: str | None = None
+
+    @property
+    def bearer(self) -> str | None:
+        """The active bearer token, or None if not yet authenticated.
+
+        In-memory only; never written to disk. Exposed so the service can
+        reuse one login across a prepare/apply pair (see seed_bearer) instead
+        of re-authenticating — which, on a personal MFA account, would prompt
+        for a second MFA code on a single write.
+        """
+        return self._bearer
+
+    def seed_bearer(self, bearer: str) -> None:
+        """Reuse a bearer obtained by an earlier client for the same identity.
+
+        Lets the service carry one authenticated session across the
+        prepare -> (random-code confirm) -> apply flow without a second login.
+        """
+        self._bearer = bearer
+        self._client.headers["Authorization"] = bearer
+
+    def _ensure_authenticated(self) -> None:
+        """Log in if not already authenticated. Idempotent on the instance."""
+        if self._bearer is not None:
+            return
+        self._bearer = self._login(self._identity.username, self._identity.password)
+        self._client.headers["Authorization"] = self._bearer
+
+    def _login(self, username: str, password: str) -> str:
+        try:
+            resp = self._client.post(
+                "/auth/login",
+                json={"email": username, "password": password},
+            )
+        except httpx.HTTPError as exc:
+            raise KeboolaApiError(
+                message=f"Developer Portal login transport error: {exc}",
+                error_code=ErrorCode.CONNECTION_ERROR,
+            ) from exc
+        if resp.status_code != 200:
+            raise KeboolaApiError(
+                message=(
+                    f"Developer Portal login failed (HTTP {resp.status_code}). "
+                    "Check the identity credentials."
+                ),
+                error_code=ErrorCode.DP_LOGIN_FAILED,
+            )
+        payload = resp.json()
+        if isinstance(payload, dict) and payload.get("token"):
+            return payload["token"]
+        # MFA path — implemented in Task 7.
+        if isinstance(payload, dict) and payload.get("session"):
+            return self._login_with_mfa(username, payload["session"])
+        raise KeboolaApiError(
+            message="Developer Portal login response missing token and session",
+            error_code=ErrorCode.DP_LOGIN_FAILED,
+        )
+
+    def _login_with_mfa(self, username: str, session: str) -> str:
+        """Confirm an MFA-gated login.
+
+        Per the Keboola Developer Portal apiary spec, the same POST /auth/login
+        endpoint accepts {email, session, code, challenge}. The `challenge`
+        field is documented as optional with default SOFTWARE_TOKEN_MFA, but
+        in practice the server rejects calls that omit it (404 with the
+        misleading "must be one of" enum message attached to the admin schema).
+        Send it explicitly. Single attempt only -- /auth/login consumes the
+        session, so any retry on the same session always 404s with "Invalid
+        code or auth state for the user" regardless of the new challenge type.
+        """
+        code = _tty_prompt("MFA code: ")
+        if not code:
+            raise KeboolaApiError(
+                message=(
+                    "Developer Portal identity requires an MFA code, but no "
+                    "interactive terminal is available. Run from a real "
+                    "terminal, or switch to a service.{vendor}.{id} "
+                    "account (no MFA)."
+                ),
+                error_code=ErrorCode.DP_MFA_REQUIRED,
+            )
+        body = {
+            "email": username,
+            "session": session,
+            "code": code.strip(),
+            "challenge": DP_MFA_CHALLENGE_TYPE,
+        }
+        try:
+            resp = self._client.post("/auth/login", json=body)
+        except httpx.HTTPError as exc:
+            raise KeboolaApiError(
+                message=f"Developer Portal MFA login transport error: {exc}",
+                error_code=ErrorCode.CONNECTION_ERROR,
+            ) from exc
+        if resp.status_code == 200:
+            payload = resp.json()
+            if isinstance(payload, dict) and payload.get("token"):
+                return payload["token"]
+            raise KeboolaApiError(
+                message=(
+                    "Developer Portal MFA login returned HTTP 200 but no "
+                    f"'token' field in response: {payload!r}"
+                ),
+                error_code=ErrorCode.DP_LOGIN_FAILED,
+            )
+        try:
+            body_text = resp.text[:MAX_API_ERROR_LENGTH]
+        except (UnicodeDecodeError, AttributeError):
+            body_text = "<unreadable>"
+        raise KeboolaApiError(
+            message=(
+                f"Developer Portal MFA login failed (HTTP {resp.status_code}): "
+                f"{body_text}. If your TOTP code rotates every 30s, this is "
+                "often a stale code -- retry promptly. If the server says "
+                "'Invalid code or auth state' on a fresh session, the code "
+                "itself was wrong."
+            ),
+            error_code=ErrorCode.DP_LOGIN_FAILED,
+        )
+
+    # ----- Reads -----
+
+    def list_apps(self, vendor: str) -> list[dict[str, Any]]:
+        self._ensure_authenticated()
+        resp = self._do_request("GET", f"/vendors/{vendor}/apps?limit=1000")
+        if resp.status_code != 200:
+            self._raise_dp_error(resp, action="list apps", vendor=vendor)
+        payload = resp.json()
+        if isinstance(payload, dict) and "apps" in payload:
+            return list(payload["apps"])
+        if isinstance(payload, list):
+            return payload
+        return []
+
+    def get_app(self, vendor: str, app_id: str) -> dict[str, Any]:
+        self._ensure_authenticated()
+        try:
+            resp = self._do_request("GET", f"/vendors/{vendor}/apps/{app_id}")
+        except KeboolaApiError as exc:
+            if exc.error_code == ErrorCode.NOT_FOUND:
+                raise KeboolaApiError(
+                    message=f"Developer Portal app '{app_id}' not found in vendor '{vendor}'",
+                    error_code=ErrorCode.DP_APP_NOT_FOUND,
+                ) from exc
+            raise
+        return resp.json()
+
+    # ----- Writes -----
+
+    def create_app(self, vendor: str, payload: dict[str, Any]) -> dict[str, Any]:
+        self._ensure_authenticated()
+        resp = self._do_request("POST", f"/vendors/{vendor}/apps", json=payload)
+        if resp.status_code not in (200, 201):
+            self._raise_dp_error(resp, action="create app", vendor=vendor)
+        return resp.json()
+
+    def patch_app(self, vendor: str, app_id: str, payload: dict[str, Any]) -> dict[str, Any]:
+        """PATCH an app. Routes by identity role:
+        - admin -> PATCH /admin/apps/{app_id} (permissive schema, accepts the
+          9 fields forbidden() on the vendor schema: complexity, categories,
+          forwardToken, forwardTokenDetails, injectEnvironment, processTimeout,
+          requiredMemory, features, category).
+        - vendor -> PATCH /vendors/{vendor}/apps/{app_id} (default, restricted
+          schema). The `vendor` arg is still required for the path.
+        """
+        self._ensure_authenticated()
+        if self._identity.role_hint == "admin":
+            path = f"/admin/apps/{app_id}"
+        else:
+            path = f"/vendors/{vendor}/apps/{app_id}"
+        resp = self._do_request("PATCH", path, json=payload)
+        if resp.status_code not in (200, 204):
+            self._raise_dp_error(resp, action="patch app", vendor=vendor, app_id=app_id)
+        return resp.json() if resp.content else {}
+
+    def publish_app(self, vendor: str, app_id: str) -> dict[str, Any]:
+        self._ensure_authenticated()
+        resp = self._do_request("POST", f"/vendors/{vendor}/apps/{app_id}/publish")
+        if resp.status_code not in (200, 202):
+            self._raise_dp_error(resp, action="publish app", vendor=vendor, app_id=app_id)
+        return resp.json() if resp.content else {"status": "submitted"}
+
+    def deprecate_app(self, vendor: str, app_id: str) -> dict[str, Any]:
+        self._ensure_authenticated()
+        resp = self._do_request("POST", f"/vendors/{vendor}/apps/{app_id}/deprecate")
+        if resp.status_code not in (200, 202):
+            self._raise_dp_error(resp, action="deprecate app", vendor=vendor, app_id=app_id)
+        return resp.json() if resp.content else {"status": "deprecated"}
+
+    def upload_icon(self, vendor: str, app_id: str, png_bytes: bytes) -> None:
+        """Two-hop icon upload: ask the portal for a presigned S3 URL, then PUT bytes there.
+
+        The S3 PUT does NOT use this client's httpx instance (no retry, no auth,
+        no User-Agent injection). We use urllib directly so the wire shape stays
+        exactly what S3 expects.
+        """
+        self._ensure_authenticated()
+        try:
+            resp = self._do_request("POST", f"/vendors/{vendor}/apps/{app_id}/icon")
+        except KeboolaApiError as exc:
+            raise KeboolaApiError(
+                message=(f"Developer Portal failed to mint icon-upload URL: {exc.message}"),
+                error_code=ErrorCode.DP_ICON_UPLOAD_FAILED,
+            ) from exc
+        if resp.status_code != 200:
+            raise KeboolaApiError(
+                message=(
+                    f"Developer Portal failed to mint icon-upload URL (HTTP {resp.status_code})"
+                ),
+                error_code=ErrorCode.DP_ICON_UPLOAD_FAILED,
+            )
+        payload = resp.json()
+        link = payload.get("link") if isinstance(payload, dict) else None
+        if not link:
+            raise KeboolaApiError(
+                message="Developer Portal icon-upload response missing 'link'",
+                error_code=ErrorCode.DP_ICON_UPLOAD_FAILED,
+            )
+        req = urllib.request.Request(
+            link,
+            data=png_bytes,
+            headers={"Content-Type": "image/png"},
+            method="PUT",
+        )
+        try:
+            with urllib.request.urlopen(req) as s3_resp:
+                if getattr(s3_resp, "status", 200) >= 300:
+                    raise KeboolaApiError(
+                        message=f"Icon S3 PUT failed (HTTP {s3_resp.status})",
+                        error_code=ErrorCode.DP_ICON_UPLOAD_FAILED,
+                    )
+        except urllib.error.HTTPError as exc:
+            raise KeboolaApiError(
+                message=f"Icon S3 PUT failed (HTTP {exc.code}): {exc.reason}",
+                error_code=ErrorCode.DP_ICON_UPLOAD_FAILED,
+            ) from exc
+
+    # ----- Error mapping -----
+
+    def _raise_dp_error(
+        self,
+        resp: httpx.Response,
+        *,
+        action: str,
+        vendor: str | None = None,
+        app_id: str | None = None,
+    ) -> None:
+        try:
+            body = resp.json()
+        except ValueError:
+            body = resp.text
+        ctx = f"{action}"
+        if vendor:
+            ctx += f" (vendor={vendor})"
+        if app_id:
+            ctx += f" (app={app_id})"
+        raise KeboolaApiError(
+            message=f"Developer Portal {ctx} failed (HTTP {resp.status_code}): {body}",
+            error_code=ErrorCode.API_ERROR,
+        )