vertracloud-api 0.3.0__tar.gz → 0.3.2__tar.gz

{vertracloud_api-0.3.0 → vertracloud_api-0.3.2}/CHANGELOG.md

@@ -1,5 +1,20 @@
 # Changelog
 
+## [0.3.2](https://github.com/vertracloud/sdk-api-py/compare/v0.3.1...v0.3.2) (2026-10-25)
+
+
+### Features
+
+* add images resource and database engine versions ([2136b86](https://github.com/vertracloud/sdk-api-py/commit/2136b86739608096c9e4590589b3aca2f42d1777))
+
+## [0.3.1](https://github.com/vertracloud/sdk-api-py/compare/v0.3.0...v0.3.1) (2026-10-22)
+
+
+### Features
+
+* **apps:** Deno, .NET and Elixir and language on create ([c7a7bb3](https://github.com/vertracloud/sdk-api-py/commit/c7a7bb3e4141d8f0c45853807acfd49719841100))
+* **apps:** remove cleanup_old_runtime_language from the restart body ([e8aa75d](https://github.com/vertracloud/sdk-api-py/commit/e8aa75daf69752af8ea16048e84e85857f613ff4))
+
 ## [0.3.0](https://github.com/vertracloud/sdk-api-py/compare/v0.2.2...v0.3.0) (2026-10-22)
 
 

{vertracloud_api-0.3.0 → vertracloud_api-0.3.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: vertracloud-api
-Version: 0.3.0
+Version: 0.3.2
 Summary: Official Python SDK for the public API of Vertra Cloud, a Brazilian application hosting platform (PaaS).
 Project-URL: Homepage, https://vertracloud.app
 Project-URL: Documentation, https://docs.vertracloud.app/sdks
@@ -76,7 +76,7 @@ client = VertraClient(
 
 ### Per-call options
 
-Methods on apps and databases take a keyword-only `workspace_id`; downloads, uploads and streams also take `timeout`:
+Methods on apps, databases and images take a keyword-only `workspace_id`; downloads, uploads and streams also take `timeout`:
 
 ```python
 # Act on a resource that belongs to a workspace
@@ -177,7 +177,7 @@ except vertracloud.WaitTimeoutError:  # still building after `timeout` seconds
     ...
 ```
 
-`missing_dependencies` on the app is filled only after the build ends. Before it ends, calls that need a stopped or running app can fail with `APP_BUILDING` (409).
+While the build runs, calls that need a stopped or running app can fail with `APP_BUILDING` (409).
 
 ### Realtime logs (SSE)
 
@@ -214,6 +214,66 @@ client.blob.delete_many(prefix="tmp/")
 
 `data` can be `bytes`, a file path, or a seekable binary file. Up to 5 MB it is one request; larger files go straight to storage in parts, with a retry per part. If the process dies halfway, `client.blob.resume(upload_id, data)` sends only the missing parts.
 
+### Custom Docker images
+
+An image is a build context (a ZIP of up to 100 MB, or a GitHub repository) with a `Dockerfile` at its root. Create and rebuild reply right away with `status: "building"`; the build then ends as `success` or `failed`, and `error` says why. Whether your plan can create images is decided by the API (`PLAN_DOES_NOT_SUPPORT_CUSTOM_IMAGES`).
+
+```python
+# From a ZIP: the file is passed as bytes, like apps.create
+with open("projeto.zip", "rb") as f:
+    image = client.images.create({"name": "meu-projeto"}, file=f.read())
+
+# Or from GitHub: `github_branch` is optional (default: the repository's default branch). A repository in your
+# GitHub App installations is linked and each push to the branch rebuilds the image; a public repository outside
+# them is built once, with no link.
+site = client.images.create({"name": "site", "github_repository": "acme/site", "github_branch": "main"})
+
+# Check the Dockerfile before building; `refusals` block the build, `warnings` do not
+report = client.images.check({"dockerfile": dockerfile_text, "files": ["Dockerfile", "app.py"]})
+
+# Follow the build as lines of text; the stream repeats the history, then goes live
+for line in client.images.logs(image["id"]):
+    print(line)
+
+image = client.images.get(image["id"])  # then status is "success" or "failed"
+
+app = client.apps.create_from_image(
+    {"image_id": image["id"], "name": "meu-app", "memory": 512, "web": True, "subdomain": "random"}
+)
+```
+
+Images can belong to a workspace, like apps. `list` and every method that acts on an existing image take a keyword-only `workspace_id`; `create` and `apps.create_from_image` take it in the body (`{"name": "site", "workspace_id": workspace_id, ...}`). `check` only reads the `Dockerfile` you send, so it has no workspace.
+
+```python
+images = client.images.list(workspace_id=workspace_id)
+client.images.rebuild(image_id, file=zip_bytes, workspace_id=workspace_id)
+```
+
+`create` takes an optional `description` (up to 128 characters). `update` renames the image and/or changes its description without building anything; the apps keep running. Send only what changes, and `None` removes the description:
+
+```python
+client.images.update(image["id"], {"name": "meu-projeto-base", "description": "Base Node 22"})
+client.images.update(image["id"], {"description": None})
+```
+
+`images.logs` returns an iterator with `close()`, like `apps.realtime`. `rebuild(image_id, file=...)` replaces the whole build context; it never restarts the apps that run the image. `link_github` and `unlink_github` change the GitHub link, and `versions` lists the successful builds, newest first.
+
+`delete` removes the image and **every app created from it**. The name must be typed back as `confirm_name`:
+
+```python
+client.images.delete(image["id"], confirm_name="meu-projeto")  # {"deleted_apps": [...]}
+```
+
+### Database versions
+
+```python
+catalog = client.databases.versions()  # keyed by engine type, as a string
+db = client.databases.create({"name": "meu-db", "type": 1, "ram": 512, "version": catalog["1"]["recommended"]})
+print(db["version"])  # major line, e.g. "18"
+```
+
+Omit `version` to get the recommended one; with `snapshot_id`, omit it to keep the snapshot's line (an older one fails with `SNAPSHOT_VERSION_NEWER`, an unknown one with `INVALID_DATABASE_VERSION`). A database's version cannot be changed after creation; security updates are applied when it is stopped and started.
+
 ### Errors
 
 Every non-2xx response raises a `VertraAPIError` carrying the HTTP `status`, the API `code` (e.g. `APP_NOT_FOUND`) and `details`; `str(err)` includes the message. The API key is never part of the error, even when it is printed:
@@ -245,8 +305,9 @@ client = VertraClient(api_key="test", transport=my_fake_transport)
 
 | Domain | Resource | Routes |
 |---|---|---|
-| Apps | `client.apps` (+ `.deploys`, `.releases`, `.domains`, `.network`, `.envs`, `.files`) | 42 |
-| Databases | `client.databases` (+ `.credentials`) | 13 |
+| Apps | `client.apps` (+ `.deploys`, `.releases`, `.domains`, `.network`, `.envs`, `.files`) | 43 |
+| Databases | `client.databases` (+ `.credentials`) | 14 |
+| Custom images | `client.images` | 12 |
 | Snapshots | `client.snapshots` | 5 |
 | Account | `client.account` (+ `.sessions`, `.folders`, `.favorites`) | 10 |
 | Workspaces | `client.workspaces` (+ `.members`, `.roles`, `.invites`, `.action_requests`, `.apps`, `.databases`, `.folders`, `.favorites`) | 30 |

{vertracloud_api-0.3.0 → vertracloud_api-0.3.2}/README.md

@@ -57,7 +57,7 @@ client = VertraClient(
 
 ### Per-call options
 
-Methods on apps and databases take a keyword-only `workspace_id`; downloads, uploads and streams also take `timeout`:
+Methods on apps, databases and images take a keyword-only `workspace_id`; downloads, uploads and streams also take `timeout`:
 
 ```python
 # Act on a resource that belongs to a workspace
@@ -158,7 +158,7 @@ except vertracloud.WaitTimeoutError:  # still building after `timeout` seconds
     ...
 ```
 
-`missing_dependencies` on the app is filled only after the build ends. Before it ends, calls that need a stopped or running app can fail with `APP_BUILDING` (409).
+While the build runs, calls that need a stopped or running app can fail with `APP_BUILDING` (409).
 
 ### Realtime logs (SSE)
 
@@ -195,6 +195,66 @@ client.blob.delete_many(prefix="tmp/")
 
 `data` can be `bytes`, a file path, or a seekable binary file. Up to 5 MB it is one request; larger files go straight to storage in parts, with a retry per part. If the process dies halfway, `client.blob.resume(upload_id, data)` sends only the missing parts.
 
+### Custom Docker images
+
+An image is a build context (a ZIP of up to 100 MB, or a GitHub repository) with a `Dockerfile` at its root. Create and rebuild reply right away with `status: "building"`; the build then ends as `success` or `failed`, and `error` says why. Whether your plan can create images is decided by the API (`PLAN_DOES_NOT_SUPPORT_CUSTOM_IMAGES`).
+
+```python
+# From a ZIP: the file is passed as bytes, like apps.create
+with open("projeto.zip", "rb") as f:
+    image = client.images.create({"name": "meu-projeto"}, file=f.read())
+
+# Or from GitHub: `github_branch` is optional (default: the repository's default branch). A repository in your
+# GitHub App installations is linked and each push to the branch rebuilds the image; a public repository outside
+# them is built once, with no link.
+site = client.images.create({"name": "site", "github_repository": "acme/site", "github_branch": "main"})
+
+# Check the Dockerfile before building; `refusals` block the build, `warnings` do not
+report = client.images.check({"dockerfile": dockerfile_text, "files": ["Dockerfile", "app.py"]})
+
+# Follow the build as lines of text; the stream repeats the history, then goes live
+for line in client.images.logs(image["id"]):
+    print(line)
+
+image = client.images.get(image["id"])  # then status is "success" or "failed"
+
+app = client.apps.create_from_image(
+    {"image_id": image["id"], "name": "meu-app", "memory": 512, "web": True, "subdomain": "random"}
+)
+```
+
+Images can belong to a workspace, like apps. `list` and every method that acts on an existing image take a keyword-only `workspace_id`; `create` and `apps.create_from_image` take it in the body (`{"name": "site", "workspace_id": workspace_id, ...}`). `check` only reads the `Dockerfile` you send, so it has no workspace.
+
+```python
+images = client.images.list(workspace_id=workspace_id)
+client.images.rebuild(image_id, file=zip_bytes, workspace_id=workspace_id)
+```
+
+`create` takes an optional `description` (up to 128 characters). `update` renames the image and/or changes its description without building anything; the apps keep running. Send only what changes, and `None` removes the description:
+
+```python
+client.images.update(image["id"], {"name": "meu-projeto-base", "description": "Base Node 22"})
+client.images.update(image["id"], {"description": None})
+```
+
+`images.logs` returns an iterator with `close()`, like `apps.realtime`. `rebuild(image_id, file=...)` replaces the whole build context; it never restarts the apps that run the image. `link_github` and `unlink_github` change the GitHub link, and `versions` lists the successful builds, newest first.
+
+`delete` removes the image and **every app created from it**. The name must be typed back as `confirm_name`:
+
+```python
+client.images.delete(image["id"], confirm_name="meu-projeto")  # {"deleted_apps": [...]}
+```
+
+### Database versions
+
+```python
+catalog = client.databases.versions()  # keyed by engine type, as a string
+db = client.databases.create({"name": "meu-db", "type": 1, "ram": 512, "version": catalog["1"]["recommended"]})
+print(db["version"])  # major line, e.g. "18"
+```
+
+Omit `version` to get the recommended one; with `snapshot_id`, omit it to keep the snapshot's line (an older one fails with `SNAPSHOT_VERSION_NEWER`, an unknown one with `INVALID_DATABASE_VERSION`). A database's version cannot be changed after creation; security updates are applied when it is stopped and started.
+
 ### Errors
 
 Every non-2xx response raises a `VertraAPIError` carrying the HTTP `status`, the API `code` (e.g. `APP_NOT_FOUND`) and `details`; `str(err)` includes the message. The API key is never part of the error, even when it is printed:
@@ -226,8 +286,9 @@ client = VertraClient(api_key="test", transport=my_fake_transport)
 
 | Domain | Resource | Routes |
 |---|---|---|
-| Apps | `client.apps` (+ `.deploys`, `.releases`, `.domains`, `.network`, `.envs`, `.files`) | 42 |
-| Databases | `client.databases` (+ `.credentials`) | 13 |
+| Apps | `client.apps` (+ `.deploys`, `.releases`, `.domains`, `.network`, `.envs`, `.files`) | 43 |
+| Databases | `client.databases` (+ `.credentials`) | 14 |
+| Custom images | `client.images` | 12 |
 | Snapshots | `client.snapshots` | 5 |
 | Account | `client.account` (+ `.sessions`, `.folders`, `.favorites`) | 10 |
 | Workspaces | `client.workspaces` (+ `.members`, `.roles`, `.invites`, `.action_requests`, `.apps`, `.databases`, `.folders`, `.favorites`) | 30 |

{vertracloud_api-0.3.0 → vertracloud_api-0.3.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "vertracloud-api"
-version = "0.3.0"
+version = "0.3.2"
 description = "Official Python SDK for the public API of Vertra Cloud, a Brazilian application hosting platform (PaaS)."
 readme = "README.md"
 license = "MIT"

{vertracloud_api-0.3.0 → vertracloud_api-0.3.2}/src/vertracloud/client.py

@@ -16,7 +16,7 @@ from .sse import SseStream
 from .transport import Response, Transport, UrllibTransport
 from .types import JsonValue
 
-__version__ = "0.3.0"  # x-release-please-version
+__version__ = "0.3.2"  # x-release-please-version
 
 DEFAULT_BASE_URL = "https://api.vertracloud.app"
 DEFAULT_BLOB_BASE_URL = "https://blob.vertracloud.app/v1"
@@ -136,11 +136,13 @@ class VertraClient:
         from .resources.billing import BillingResource
         from .resources.blob import BlobResource
         from .resources.databases import DatabasesResource
+        from .resources.images import ImagesResource
         from .resources.snapshots import SnapshotsResource
         from .resources.workspaces import WorkspacesResource
 
         self.apps = AppsResource(self)
         self.databases = DatabasesResource(self)
+        self.images = ImagesResource(self)
         self.snapshots = SnapshotsResource(self)
         self.account = AccountResource(self)
         self.workspaces = WorkspacesResource(self)

{vertracloud_api-0.3.0 → vertracloud_api-0.3.2}/src/vertracloud/errors.py

@@ -32,6 +32,19 @@ class VertraAPIError(Exception):
     def __repr__(self) -> str:
         return f"{self.__class__.__name__}(status={self.status!r}, code={self.code!r})"
 
+    @property
+    def issues(self) -> list[dict[str, Any]]:
+        """Findings of a `DOCKERFILE_REFUSED` error: the objects in `details.issues`, as the API sent them
+        (`{code, line}`). Tolerant on purpose: any other error, or a `details` of another shape, gives `[]`
+        and never raises; entries that are not objects are skipped."""
+        details = self.details
+        if not isinstance(details, dict):
+            return []
+        raw = details.get("issues")
+        if not isinstance(raw, list):
+            return []
+        return [item for item in raw if isinstance(item, dict)]
+
 
 class AuthenticationError(VertraAPIError):
     """401 — invalid key or user not found (`API_KEY_INVALID`, `USER_NOT_FOUND`)."""

{vertracloud_api-0.3.0 → vertracloud_api-0.3.2}/src/vertracloud/resources/apps.py

@@ -1,4 +1,4 @@
-"""`apps` domain — 42 routes (scopes `apps:read/write/delete/envs/files`).
+"""`apps` domain — 43 routes (scopes `apps:read/write/delete/envs/files`).
 
 `workspace_id` is accepted as an optional query parameter on almost every method.
 """
@@ -15,6 +15,7 @@ from ..types import (
     AddDomainBody,
     APIAppFileUploadResponse,
     APIApplication,
+    APIApplicationCreated,
     APIApplicationDeployment,
     APIApplicationDomain,
     APIApplicationDomainConnect,
@@ -29,11 +30,13 @@ from ..types import (
     APIApplicationRollbackPreview,
     APIApplicationStatus,
     APIApplicationStatusShort,
+    APIApplicationWebhook,
     APIApplicationWebPublish,
     APIRuntimesResponse,
     APISubdomainResponse,
     APIWebhookUrl,
     CreateAppBody,
+    CreateAppFromImageBody,
     CreateWebhookBody,
     EnvironmentSetBody,
     JsonValue,
@@ -61,7 +64,7 @@ class AppDeploysWebhookResource:
     def __init__(self, client: VertraClient) -> None:
         self._c = client
 
-    def get(self, app_id: str, *, workspace_id: str | None = None) -> APIWebhookUrl:
+    def get(self, app_id: str, *, workspace_id: str | None = None) -> APIApplicationWebhook:
         """GET /v1/apps/:id/deploys/webhook — scope `apps:read`.
         Doc: https://docs.vertracloud.app/api-reference/endpoint/apps/deploys/webhookurl
         """
@@ -255,7 +258,9 @@ class AppNetworkResource:
         self, app_id: str, body: PublishAppBody | None = None, *, workspace_id: str | None = None
     ) -> APIApplicationWebPublish:
         """POST /v1/apps/:id/network/publish — scope `apps:write`. The Pro plan gets a random
-        subdomain, Scale picks its own; an empty `{}` body is valid."""
+        subdomain, Scale picks its own; an empty `{}` body is valid. `port` (only for an app on a
+        custom image) is the port the image listens on; it is required when the app has no web
+        port yet."""
         return self._c.request_json(
             "POST",
             f"/v1/apps/{encode_path_param(app_id)}/network/publish",
@@ -467,9 +472,10 @@ class AppsResource:
         file: bytes | None = None,
         filename: str = "app.zip",
         timeout: float | None = None,
-    ) -> APIApplication:
+    ) -> APIApplicationCreated:
         """POST /v1/apps — scope `apps:write`. Multipart: field `file` (zip) OR `snapshot_id`
-        in `body`, other fields as text parts. Rate limit 15/min, plus the plan's
+        in `body`, other fields as text parts. A snapshot of an app on a custom image can come with
+        `warning` (`IMAGE_VERSION_NOT_FOUND`). Rate limit 15/min, plus the plan's
         deploys-per-hour cap. Replies 202 with `status: "building"`: the build continues in the
         background — use `wait_until_ready`, `logs` or `realtime` to follow it.
         Doc: https://docs.vertracloud.app/api-reference/endpoint/apps/create
@@ -492,6 +498,15 @@ class AppsResource:
             "POST", "/v1/apps", fields=fields, timeout=timeout if timeout is not None else LARGE_PAYLOAD_TIMEOUT
         )
 
+    def create_from_image(self, body: CreateAppFromImageBody) -> APIApplication:
+        """POST /v1/apps/image — scope `apps:write`. JSON. Creates an app that runs from a custom
+        image, which must be ready (`images.get(...)["status"] == "success"`). Replies 202 with
+        `status: "building"` and `custom_image` filled in; follow the build as with `create`.
+        `web: False` makes an app without traffic; `subdomain` and `port` need `web: True`.
+        Doc: https://docs.vertracloud.app/api-reference/endpoint/apps/create-from-image
+        """
+        return self._c.request_json("POST", "/v1/apps/image", json_body=body)
+
     def wait_until_ready(
         self,
         app_id: str,
@@ -534,7 +549,7 @@ class AppsResource:
         self, app_id: str, body: RestartAppBody | None = None, *, workspace_id: str | None = None
     ) -> APIApplicationOperationResponse:
         """POST /v1/apps/:id/restart — scope `apps:write`. Flags: `reinstall_dependencies`,
-        `force_build`, `cleanup_old_runtime_language`."""
+        `force_build`."""
         return self._c.request_json(
             "POST",
             f"/v1/apps/{encode_path_param(app_id)}/restart",

{vertracloud_api-0.3.0 → vertracloud_api-0.3.2}/src/vertracloud/resources/databases.py

@@ -1,4 +1,4 @@
-"""`databases` domain — 13 routes (scopes `databases:read/write/delete/credentials`)."""
+"""`databases` domain — 14 routes (scopes `databases:read/write/delete/credentials`)."""
 
 from __future__ import annotations
 
@@ -11,6 +11,7 @@ from ..types import (
     APIDatabasePasswordReset,
     APIDatabaseStatus,
     APIDatabaseStatusShort,
+    APIDatabaseVersions,
     APIOperationResponse,
     CreateDatabaseBody,
     UpdateDatabaseBody,
@@ -63,7 +64,7 @@ class DatabaseCredentialsResource:
 
 
 class DatabasesResource:
-    """`databases.*` — statusAll/get/status/metrics/create/update/start/stop/reset/delete +
+    """`databases.*` — status_all/versions/get/status/metrics/create/update/start/stop/reset/delete +
     `credentials`."""
 
     def __init__(self, client: VertraClient) -> None:
@@ -74,6 +75,12 @@ class DatabasesResource:
         """GET /v1/databases/status — scope `databases:read`."""
         return self._c.request_json("GET", "/v1/databases/status", query={"workspace_id": workspace_id})
 
+    def versions(self) -> APIDatabaseVersions:
+        """GET /v1/databases/versions — scope `databases:read`. Catalog keyed by engine `type`:
+        `recommended` and `available` lines for new databases. A database's version cannot be
+        changed after creation; security updates are applied when it is stopped and started."""
+        return self._c.request_json("GET", "/v1/databases/versions")
+
     def get(self, db_id: str, *, workspace_id: str | None = None) -> APIDatabase:
         """GET /v1/databases/:id — scope `databases:read`."""
         return self._c.request_json(
@@ -93,7 +100,8 @@ class DatabasesResource:
         )
 
     def create(self, body: CreateDatabaseBody) -> APIDatabase:
-        """POST /v1/databases — scope `databases:write`."""
+        """POST /v1/databases — scope `databases:write`.
+        Errors: `INVALID_DATABASE_VERSION`, `SNAPSHOT_VERSION_NEWER`."""
         return self._c.request_json("POST", "/v1/databases", json_body=body)
 
     def update(self, db_id: str, body: UpdateDatabaseBody, *, workspace_id: str | None = None) -> APIDatabase:

vertracloud_api-0.3.2/src/vertracloud/resources/images.py

@@ -0,0 +1,239 @@
+"""`images` domain — custom Docker images (scopes `images:read`, `images:write` and `images:delete`).
+
+A custom image is a build context with a `Dockerfile`, built by the platform in isolation.
+`apps.create_from_image` (scope `apps:write`) runs an app from a ready image. Create and rebuild
+reply 202 with `status: "building"`: follow the build with `logs`, or poll `get` until `status`
+is `success` or `failed`.
+
+`workspace_id` is a keyword-only query parameter on the routes that act on an existing image and
+on `list`. Without it the call acts on the caller's own images, as the apps routes do.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterator
+from typing import TYPE_CHECKING
+
+from ..client import LARGE_PAYLOAD_TIMEOUT, MultipartField, encode_path_param
+from ..sse import SseStream
+from ..types import (
+    APICustomImage,
+    APICustomImageContext,
+    APICustomImageDeleteResult,
+    APICustomImageVersion,
+    APIDockerfileCheck,
+    CheckDockerfileBody,
+    CreateCustomImageBody,
+    CustomImageGithubBody,
+    UpdateCustomImageBody,
+)
+
+if TYPE_CHECKING:
+    from ..client import VertraClient
+
+# Aliases so `list[...]` doesn't resolve to the `list` method inside the class itself.
+ImageList = list[APICustomImage]
+ImageVersionList = list[APICustomImageVersion]
+
+
+class ImageLogStream:
+    """Build log of an image, as lines. Iterate it for the text of each `log` event; `close()`
+    stops following a live build. Other events (`system`, `heartbeat`) are skipped."""
+
+    def __init__(self, stream: SseStream) -> None:
+        self._stream = stream
+
+    def __iter__(self) -> Iterator[str]:
+        for event in self._stream:
+            if event.event == "log":
+                yield event.data
+
+    def close(self) -> None:
+        self._stream.close()
+
+
+class ImagesResource:
+    """`images.*` — list/get/create/update/rebuild/delete/versions/logs/context/link_github/unlink_github/check."""
+
+    def __init__(self, client: VertraClient) -> None:
+        self._c = client
+
+    def list(self, *, workspace_id: str | None = None) -> ImageList:
+        """GET /v1/images — scope `images:read`. With `workspace_id`, lists the images of that workspace.
+        Doc: https://docs.vertracloud.app/api-reference/endpoint/images/list
+        """
+        return self._c.request_json("GET", "/v1/images", query={"workspace_id": workspace_id})
+
+    def get(self, image_id: str, *, workspace_id: str | None = None) -> APICustomImage:
+        """GET /v1/images/:image_id — scope `images:read`. `status` is the state of the latest build;
+        `current_version_id` and `digest` are `None` until a build succeeds.
+        Doc: https://docs.vertracloud.app/api-reference/endpoint/images/get
+        """
+        return self._c.request_json(
+            "GET", f"/v1/images/{encode_path_param(image_id)}", query={"workspace_id": workspace_id}
+        )
+
+    def create(
+        self,
+        body: CreateCustomImageBody,
+        *,
+        file: bytes | None = None,
+        filename: str = "image.zip",
+        timeout: float | None = None,
+    ) -> APICustomImage:
+        """POST /v1/images — scope `images:write`. Multipart. The source is either `file` (a ZIP
+        of up to 100 MB, with a `Dockerfile` at its root) or `body["github_repository"]`;
+        `body["github_branch"]` is optional (default: the repository's default branch). A repository
+        in your GitHub App installations is linked and each push to the branch rebuilds the image; a
+        public repository outside them is built once, with no link (`github` is `None`). Raises
+        `ValueError` before any request when the source is missing, doubled, or a branch comes without
+        a repository. Replies 202 with `status: "building"`.
+        Errors: `PLAN_DOES_NOT_SUPPORT_CUSTOM_IMAGES`, `MAX_IMAGES_REACHED`, `DOCKERFILE_NOT_FOUND`,
+        `DOCKERFILE_REFUSED` (its `issues` attribute lists the findings), `IMAGE_CONTEXT_TOO_LARGE`,
+        `IMAGE_BUILDER_UNAVAILABLE`, `INSTALLATION_NOT_FOUND` (a private or missing repository outside
+        your installations).
+        Doc: https://docs.vertracloud.app/api-reference/endpoint/images/create
+        """
+        repository = body.get("github_repository")
+        branch = body.get("github_branch")
+        if file is not None and (repository is not None or branch is not None):
+            raise ValueError("pass either file or github_repository (with github_branch), not both")
+        if file is None and repository is None:
+            raise ValueError("pass file, or github_repository (with an optional github_branch)")
+
+        fields = [MultipartField("name", body["name"])]
+        description = body.get("description")
+        if description is not None:
+            fields.append(MultipartField("description", description))
+        if file is not None:
+            fields.append(MultipartField("file", file, filename=filename))
+        if repository is not None:
+            fields.append(MultipartField("github_repository", repository))
+        if branch is not None:
+            fields.append(MultipartField("github_branch", branch))
+        workspace_id = body.get("workspace_id")
+        if workspace_id is not None:
+            fields.append(MultipartField("workspace_id", workspace_id))
+        return self._c.request_multipart(
+            "POST", "/v1/images", fields=fields, timeout=timeout if timeout is not None else LARGE_PAYLOAD_TIMEOUT
+        )
+
+    def update(self, image_id: str, body: UpdateCustomImageBody, *, workspace_id: str | None = None) -> APICustomImage:
+        """PATCH /v1/images/:image_id — scope `images:write`. Renames the image and/or changes its
+        description; send only what changes (`description: None` or an empty string removes it). Builds
+        nothing: the apps keep running and nothing restarts. Errors: `VALIDATION_ERROR` (empty body, name
+        out of range or already used by another of your images with `details.path == "name"`,
+        description too long), `IMAGE_NOT_FOUND`, `ACCESS_DENIED` (system images cannot be changed).
+        Doc: https://docs.vertracloud.app/api-reference/endpoint/images/update
+        """
+        return self._c.request_json(
+            "PATCH",
+            f"/v1/images/{encode_path_param(image_id)}",
+            json_body=body,
+            query={"workspace_id": workspace_id},
+        )
+
+    def rebuild(
+        self,
+        image_id: str,
+        *,
+        file: bytes,
+        filename: str = "image.zip",
+        workspace_id: str | None = None,
+        timeout: float | None = None,
+    ) -> APICustomImage:
+        """PUT /v1/images/:image_id — scope `images:write`. Multipart `file` replaces the whole build
+        context. Replies 202 with `status: "building"`. Refused with `IMAGE_BUILD_IN_PROGRESS` while a
+        build runs. A rebuild never restarts the apps that run the image.
+        Doc: https://docs.vertracloud.app/api-reference/endpoint/images/rebuild
+        """
+        return self._c.request_multipart(
+            "PUT",
+            f"/v1/images/{encode_path_param(image_id)}",
+            fields=[MultipartField("file", file, filename=filename)],
+            query={"workspace_id": workspace_id},
+            timeout=timeout if timeout is not None else LARGE_PAYLOAD_TIMEOUT,
+        )
+
+    def delete(
+        self, image_id: str, *, confirm_name: str, workspace_id: str | None = None
+    ) -> APICustomImageDeleteResult:
+        """DELETE /v1/images/:image_id — scope `images:delete`, and also `apps:delete` when apps run the
+        image. Body `{confirm_name}` must equal the image name (`IMAGE_NAME_MISMATCH` otherwise).
+        Deletes the versions, the context and every app created from the image; `deleted_apps` lists
+        their ids. Refused with `IMAGE_BUILD_IN_PROGRESS` while a build runs.
+        Doc: https://docs.vertracloud.app/api-reference/endpoint/images/delete
+        """
+        return self._c.request_json(
+            "DELETE",
+            f"/v1/images/{encode_path_param(image_id)}",
+            json_body={"confirm_name": confirm_name},
+            query={"workspace_id": workspace_id},
+        )
+
+    def versions(self, image_id: str, *, workspace_id: str | None = None) -> ImageVersionList:
+        """GET /v1/images/:image_id/versions — scope `images:read`. Newest first.
+        Doc: https://docs.vertracloud.app/api-reference/endpoint/images/versions
+        """
+        return self._c.request_json(
+            "GET", f"/v1/images/{encode_path_param(image_id)}/versions", query={"workspace_id": workspace_id}
+        )
+
+    def logs(
+        self,
+        image_id: str,
+        *,
+        version_id: str | None = None,
+        workspace_id: str | None = None,
+        timeout: float | None = None,
+    ) -> ImageLogStream:
+        """GET /v1/images/:image_id/logs — scope `images:read`. A Server-Sent Events stream: it repeats
+        the history of the build and then follows it live. `version_id` picks the build of one version;
+        by default it is the latest build. Iterate it for lines; `close()` or `break` ends it.
+        Doc: https://docs.vertracloud.app/api-reference/endpoint/images/logs
+        """
+        stream = self._c.request_sse(
+            f"/v1/images/{encode_path_param(image_id)}/logs",
+            query={"version_id": version_id, "workspace_id": workspace_id},
+            timeout=timeout,
+        )
+        return ImageLogStream(stream)
+
+    def context(self, image_id: str, *, workspace_id: str | None = None) -> APICustomImageContext:
+        """GET /v1/images/:image_id/context — scope `images:read`. `url` is a temporary download link
+        of the current build context.
+        Doc: https://docs.vertracloud.app/api-reference/endpoint/images/context
+        """
+        return self._c.request_json(
+            "GET", f"/v1/images/{encode_path_param(image_id)}/context", query={"workspace_id": workspace_id}
+        )
+
+    def link_github(
+        self, image_id: str, body: CustomImageGithubBody, *, workspace_id: str | None = None
+    ) -> APICustomImage:
+        """PUT /v1/images/:image_id/github — scope `images:write`. Links a repository (`owner/name`) in
+        your GitHub App installations: each push to the branch rebuilds the image. `body["branch"]` is
+        optional (default: the repository's default branch).
+        Doc: https://docs.vertracloud.app/api-reference/endpoint/images/github-link
+        """
+        return self._c.request_json(
+            "PUT",
+            f"/v1/images/{encode_path_param(image_id)}/github",
+            json_body=body,
+            query={"workspace_id": workspace_id},
+        )
+
+    def unlink_github(self, image_id: str, *, workspace_id: str | None = None) -> APICustomImage:
+        """DELETE /v1/images/:image_id/github — scope `images:write`. Unlinks the repository.
+        Doc: https://docs.vertracloud.app/api-reference/endpoint/images/github-unlink
+        """
+        return self._c.request_json(
+            "DELETE", f"/v1/images/{encode_path_param(image_id)}/github", query={"workspace_id": workspace_id}
+        )
+
+    def check(self, body: CheckDockerfileBody) -> APIDockerfileCheck:
+        """POST /v1/images/check — scope `images:read`. Checks a `Dockerfile` and the paths of its
+        context before building; creates nothing. `refusals` would block the build, `warnings` would not.
+        Doc: https://docs.vertracloud.app/api-reference/endpoint/images/check
+        """
+        return self._c.request_json("POST", "/v1/images/check", json_body=body)

{vertracloud_api-0.3.0 → vertracloud_api-0.3.2}/src/vertracloud/resources/snapshots.py

@@ -56,11 +56,25 @@ class SnapshotsResource:
             query={"scope": scope},
         )
 
-    def restore(self, resource_id: str, snapshot_id: str, scope: SnapshotScope) -> APISnapshotRestoreResponse:
-        """POST /v1/users/:id/snapshots/:snapshot_id/restore — scope `snapshots:write`."""
+    def restore(
+        self,
+        resource_id: str,
+        snapshot_id: str,
+        scope: SnapshotScope,
+        *,
+        restore_image_version: bool | None = None,
+    ) -> APISnapshotRestoreResponse:
+        """POST /v1/users/:id/snapshots/:snapshot_id/restore — scope `snapshots:write`.
+        For database snapshots it can fail with `SNAPSHOT_VERSION_NEWER`.
+        `restore_image_version` applies to an app on a custom image: `True` also goes back to the image
+        version the app ran when the snapshot was taken, if it still exists (the response then carries
+        `warning` when it does not). Omitted, the API restores only the data."""
+        body: dict[str, bool] = (
+            {} if restore_image_version is None else {"restore_image_version": restore_image_version}
+        )
         return self._c.request_json(
             "POST",
             f"/v1/users/{encode_path_param(resource_id)}/snapshots/{encode_path_param(snapshot_id)}/restore",
-            json_body={},
+            json_body=body,
             query={"scope": scope},
         )

{vertracloud_api-0.3.0 → vertracloud_api-0.3.2}/src/vertracloud/types.py

@@ -66,6 +66,7 @@ class CreateAppBody(TypedDict, total=False):
     main: str
     subdomain: str
     version: str
+    language: ApplicationLanguage
     name: str
     description: str | None
     workspace_id: str
@@ -103,7 +104,6 @@ class RollbackAppBody(TypedDict, total=False):
 
 
 class RestartAppBody(TypedDict, total=False):
-    cleanup_old_runtime_language: str
     reinstall_dependencies: bool
     force_build: bool
 
@@ -145,6 +145,9 @@ class SetSubdomainBody(TypedDict):
 
 class PublishAppBody(TypedDict, total=False):
     subdomain: str
+    # Only for an app on a custom image: the port the image listens on (1-65535).
+    # Required when the app was created without web; ignored for other apps.
+    port: int
 
 
 class PurgeCacheBody(TypedDict, total=False):
@@ -170,15 +173,23 @@ class MoveFileBody(TypedDict, total=False):
     workspace_id: str
 
 
-class CreateWebhookBody(TypedDict):
-    """Body for `apps.deploys.webhook.create` — all 4 fields are required."""
-
+class _CreateWebhookBodyRequired(TypedDict):
     owner: str
     repo_name: str
     repo_id: str
     account_id: str
 
 
+class CreateWebhookBody(_CreateWebhookBodyRequired, total=False):
+    """Body for `apps.deploys.webhook.create` — the first 4 fields are required.
+
+    `branch` is the only branch the auto-deploy reacts to. Without it, a push on `main` or `master`
+    deploys, as it always did. Linking again with another `branch` changes it; linking again
+    without one goes back to `main` or `master`."""
+
+    branch: str
+
+
 class _CreateDatabaseBodyRequired(TypedDict):
     name: str
     ram: int
@@ -192,6 +203,10 @@ class CreateDatabaseBody(_CreateDatabaseBodyRequired, total=False):
     type: int
     workspace_id: str
     snapshot_id: str
+    version: str
+    """Engine major line (see `databases.versions()`). Omitted, the recommended one is used; with
+    `snapshot_id`, omit it to keep the snapshot's line (an older one fails with `SNAPSHOT_VERSION_NEWER`,
+    an unknown one with `INVALID_DATABASE_VERSION`)."""
 
 
 class UpdateDatabaseBody(TypedDict, total=False):
@@ -295,7 +310,19 @@ class PutBillingDetailsBody(_PutBillingDetailsRequired, total=False):
 # -- responses -------------------------------------------------------------
 
 ApplicationLanguage = Literal[
-    "javascript", "typescript", "bun", "python", "static", "php", "go", "ruby", "java", "rust"
+    "javascript",
+    "typescript",
+    "bun",
+    "python",
+    "static",
+    "php",
+    "go",
+    "ruby",
+    "java",
+    "rust",
+    "deno",
+    "dotnet",
+    "elixir",
 ]
 ApplicationStatus = Literal["up", "down", "building"]
 ApplicationBuildError = Literal[
@@ -381,12 +408,20 @@ class _APIApplicationRequired(TypedDict):
     shield_cooldown: APIApplicationShieldCooldown | None
     deploy: APIApplicationDeploySettings
     last_build_error: ApplicationBuildError | None
+    # Custom Docker image the app runs from; `None` for a regular app.
+    custom_image: APIApplicationCustomImage | None
 
 
 class APIApplication(_APIApplicationRequired, total=False):
     description: str
     github: APIApplicationGithub | None
-    missing_dependencies: list[str]
+
+
+class APIApplicationCreated(APIApplication, total=False):
+    """Response of `apps.create`. `warning` is set when the app was created from the snapshot of an app
+    on a custom image and the recorded image version no longer exists: the app uses the current version."""
+
+    warning: SnapshotImageWarning
 
 
 class APIApplicationNetwork(TypedDict):
@@ -427,8 +462,11 @@ class _APIAppFileUploadResponseRequired(TypedDict):
 
 
 class APIAppFileUploadResponse(_APIAppFileUploadResponseRequired, total=False):
-    missing_dependencies: list[str]
     removed_directories: list[str]
+    # Only for a commit to an app on a custom image: the image build the commit started. `None` otherwise.
+    image_build: APIApplicationImageBuild | None
+    # Readable summary for the CLI, e.g. that the image is rebuilding.
+    message: str
 
 
 class APIApplicationMetric(TypedDict):
@@ -520,6 +558,16 @@ class APIWebhookUrl(TypedDict):
     url: str
 
 
+class APIApplicationWebhook(TypedDict):
+    """Auto-deploy webhook of an application and the repository it is linked to.
+    `branch` is `None` for a link created without one (reacts to `main` or `master`)."""
+
+    webhook_url: str
+    repo_owner: str
+    repo_name: str
+    branch: str | None
+
+
 class APISubdomainResponse(TypedDict):
     subdomain: str
 
@@ -554,12 +602,19 @@ class APIApplicationFileContent(TypedDict):
     last_modified: str
 
 
-class APIApplicationScanSuggestions(TypedDict, total=False):
+class _APIApplicationScanSuggestionsRequired(TypedDict):
+    language: ApplicationLanguage | None
+    main: str | None
+    version: str | None
+    has_manifest: bool
+    candidates: list[ApplicationLanguage]
+
+
+class APIApplicationScanSuggestions(_APIApplicationScanSuggestionsRequired, total=False):
     suggested_start_command: str
     suggested_build_command: str
     suggested_memory_mb: int
     suggested_public_web: bool
-    missing_dependencies: list[str]
 
 
 class APIRuntimeEntry(TypedDict):
@@ -587,6 +642,18 @@ class APIDatabase(TypedDict):
     updated_at: str
     last_snapshot: str | None
     offline_since: str | None
+    version: str
+    """Engine major line, e.g. `"18"` or `"8.0"`; the patch is never exposed. Not limited to the
+    catalog: older databases may report a line that is no longer offered for new ones."""
+
+
+class APIDatabaseVersionCatalog(TypedDict):
+    recommended: str
+    available: list[str]
+
+
+APIDatabaseVersions = dict[str, APIDatabaseVersionCatalog]
+"""Catalog keyed by the engine `type` as a string (`"1"`, `"2"`, ...)."""
 
 
 class APIDatabaseNetwork(TypedDict):
@@ -649,10 +716,15 @@ class APIGroupedResourceSnapshots(TypedDict):
     snapshots: list[APIResourceSnapshot]
 
 
-class APISnapshotRestoreResponse(TypedDict):
+class _APISnapshotRestoreResponseRequired(TypedDict):
     message: str
 
 
+class APISnapshotRestoreResponse(_APISnapshotRestoreResponseRequired, total=False):
+    # Set when `restore_image_version` was asked but the recorded image version is gone: only data was restored.
+    warning: SnapshotImageWarning
+
+
 class APIUser(TypedDict):
     id: str
     name: str
@@ -1116,3 +1188,163 @@ class _APIBlobCustomDomainRequired(TypedDict):
 class APIBlobCustomDomain(_APIBlobCustomDomainRequired, total=False):
     # Only while the domain is not active: the TXT record that proves ownership.
     verification: APIBlobCustomDomainVerification | None
+
+
+# -- Custom Docker images: `images.*` and `apps.create_from_image` ---------------------------
+
+CustomImageStatus = Literal["building", "success", "failed"]
+CustomImageBuildSource = Literal["upload", "commit", "github"]
+CustomImageOwner = Literal["account", "system"]
+DockerfileIssueCode = Literal[
+    "missing_dockerfile",
+    "syntax_frontend",
+    "run_security_insecure",
+    "run_network_host",
+    "mount_ssh",
+    "mount_secret",
+    "workdir_app",
+    "env_file_in_context",
+    "copy_env_file",
+    "volume_outside_app",
+    "volume_refused",
+]
+
+
+class DockerfileIssue(TypedDict):
+    """Refusals block the build; warnings do not. `line` is `None` when no line applies."""
+
+    code: DockerfileIssueCode
+    line: int | None
+
+
+class APIDockerfileCheck(TypedDict):
+    refusals: list[DockerfileIssue]
+    warnings: list[DockerfileIssue]
+    suggested_port: int
+
+
+class APICustomImageApp(TypedDict):
+    id: str
+    name: str
+    version_id: str | None
+    outdated: bool
+
+
+class APIApplicationCustomImage(APICustomImageApp):
+    """`APIApplication.custom_image`: the image the app runs from and the port it listens on."""
+
+    image_id: str
+    port: int | None
+
+
+class APICustomImageGithub(TypedDict):
+    repository: str
+    branch: str
+
+
+class APICustomImage(TypedDict):
+    id: str
+    name: str
+    # Free-text description, up to 128 characters; None when the image has none.
+    description: str | None
+    owner: CustomImageOwner
+    status: CustomImageStatus
+    error: str | None
+    digest: str | None
+    uncompressed_bytes: int | None
+    layer_count: int | None
+    # Port suggested for a new app on this image (first EXPOSE, or 80); None for images created before the field.
+    suggested_port: int | None
+    apps: list[APICustomImageApp]
+    github: APICustomImageGithub | None
+    current_version_id: str | None
+    created_at: str
+    updated_at: str
+
+
+class APICustomImageVersion(TypedDict):
+    id: str
+    digest: str
+    source: CustomImageBuildSource
+    message: str | None
+    created_at: str
+    in_use: bool
+
+
+class APICustomImageContext(TypedDict):
+    url: str
+
+
+class APICustomImageDeleteResult(TypedDict):
+    deleted_apps: list[str]
+
+
+class _CreateCustomImageRequired(TypedDict):
+    name: str
+
+
+class CreateCustomImageBody(_CreateCustomImageRequired, total=False):
+    """`POST /v1/images` fields. Exactly one source: a `file` passed to `images.create`, or
+    `github_repository` (`owner/name`). `github_branch` is optional; without it the repository's default
+    branch is used. A repository in your GitHub App installations is linked (each push to the branch
+    rebuilds the image); a public repository outside them is built once, with no link.
+    `description` is optional free text, up to 128 characters (an empty value means none)."""
+
+    description: str
+    github_repository: str
+    github_branch: str
+    workspace_id: str
+
+
+class _CustomImageGithubRequired(TypedDict):
+    repository: str
+
+
+class UpdateCustomImageBody(TypedDict, total=False):
+    """`PATCH /v1/images/:image_id` fields; send only what changes (at least one). `name` is 1 to 50
+    characters, unique among your images. `description` is up to 128 characters; `None` or an empty
+    string removes it."""
+
+    name: str
+    description: str | None
+
+
+class CustomImageGithubBody(_CustomImageGithubRequired, total=False):
+    """`PUT /v1/images/:image_id/github` fields. `branch` is optional: without it the repository's
+    default branch is used. The repository must be in one of your GitHub App installations."""
+
+    branch: str
+
+
+class CheckDockerfileBody(TypedDict):
+    dockerfile: str
+    files: list[str]
+
+
+class APIApplicationImageBuild(TypedDict):
+    """The image build started by a commit to an app on a custom image (`apps.files.upload`)."""
+
+    image_id: str
+    build_id: str
+
+
+# Warning of a snapshot restore or of a create from a snapshot: the image version the snapshot recorded was
+# removed by retention, so the app stays on the image's current version.
+SnapshotImageWarning = Literal["IMAGE_VERSION_NOT_FOUND"]
+
+
+class _CreateAppFromImageRequired(TypedDict):
+    image_id: str
+    name: str
+    memory: int
+    web: bool
+
+
+class CreateAppFromImageBody(_CreateAppFromImageRequired, total=False):
+    """`POST /v1/apps/image`. `subdomain` and `port` apply only with `web: True`."""
+
+    description: str
+    subdomain: str
+    port: int
+    envs: list[EnvEntry]
+    workspace_id: str