dominus-sdk-python 6.2.0__tar.gz → 6.3.0__tar.gz

{dominus_sdk_python-6.2.0 → dominus_sdk_python-6.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: dominus-sdk-python
-Version: 6.2.0
+Version: 6.3.0
 Summary: Python SDK for the Dominus gateway-first platform
 Author-email: CareBridge Systems <dev@carebridge.io>
 License-Expression: LicenseRef-Proprietary

{dominus_sdk_python-6.2.0 → dominus_sdk_python-6.3.0}/dominus/__init__.py

@@ -160,12 +160,19 @@ from .errors import (
     ValidationError,
     ConflictError,
     ServiceError,
+    StashBookmarkArtifactNotFound,
+    StashBookmarkInvalidVersionRef,
+    StashBookmarkDuplicateName,
+    StashBookmarkUpstreamRejected,
+    StashWatchInvalidWebhookUrl,
+    StashWatchUpstreamRejected,
+    StashWatchNotFound,
     SecureTableError,
     ConnectionError as DominusConnectionError,
     TimeoutError as DominusTimeoutError,
 )
 
-__version__ = "6.2.0"
+__version__ = "6.3.0"
 __all__ = [
     # Main SDK instance
     "dominus",
@@ -250,6 +257,13 @@ __all__ = [
     "ValidationError",
     "ConflictError",
     "ServiceError",
+    "StashBookmarkArtifactNotFound",
+    "StashBookmarkInvalidVersionRef",
+    "StashBookmarkDuplicateName",
+    "StashBookmarkUpstreamRejected",
+    "StashWatchInvalidWebhookUrl",
+    "StashWatchUpstreamRejected",
+    "StashWatchNotFound",
     "SecureTableError",
     "DominusConnectionError",
     "DominusTimeoutError",

{dominus_sdk_python-6.2.0 → dominus_sdk_python-6.3.0}/dominus/errors.py

@@ -205,6 +205,34 @@ class ServiceError(DominusError):
         super().__init__(message, status_code, details, endpoint)
 
 
+class StashBookmarkArtifactNotFound(NotFoundError):
+    """Raised when a stash artifact bookmark target cannot be found."""
+
+
+class StashBookmarkInvalidVersionRef(ValidationError):
+    """Raised when a stash artifact bookmark version_ref is invalid."""
+
+
+class StashBookmarkDuplicateName(ConflictError):
+    """Raised when a stash artifact bookmark name is already in use."""
+
+
+class StashBookmarkUpstreamRejected(ServiceError):
+    """Raised when the artifact backend rejects a stash bookmark operation."""
+
+
+class StashWatchInvalidWebhookUrl(ValidationError):
+    """Raised when a stash artifact watcher webhook_url is invalid."""
+
+
+class StashWatchUpstreamRejected(ServiceError):
+    """Raised when the artifact backend rejects a stash watch operation."""
+
+
+class StashWatchNotFound(NotFoundError):
+    """Raised when a stash artifact watcher cannot be found."""
+
+
 class ConnectionError(DominusError):
     """Raised when connection to the backend fails."""
 
@@ -244,6 +272,17 @@ class SecureTableError(DominusError):
         super().__init__(message, status_code, details, endpoint)
 
 
+STASH_ERROR_CLASSES = {
+    "stash.bookmark.artifact_not_found": StashBookmarkArtifactNotFound,
+    "stash.bookmark.invalid_version_ref": StashBookmarkInvalidVersionRef,
+    "stash.bookmark.duplicate_name": StashBookmarkDuplicateName,
+    "stash.bookmark.upstream_rejected": StashBookmarkUpstreamRejected,
+    "stash.watch.invalid_webhook_url": StashWatchInvalidWebhookUrl,
+    "stash.watch.upstream_rejected": StashWatchUpstreamRejected,
+    "stash.watch.not_found": StashWatchNotFound,
+}
+
+
 def raise_for_status(
     status_code: int,
     message: str,
@@ -262,6 +301,7 @@ def raise_for_status(
     Raises:
         Appropriate DominusError subclass
     """
+    code = _first_string((details or {}).get("code"))
     error_classes = {
         400: ValidationError,
         401: AuthenticationError,
@@ -274,5 +314,5 @@ def raise_for_status(
         504: TimeoutError,
     }
 
-    error_class = error_classes.get(status_code, DominusError)
+    error_class = STASH_ERROR_CLASSES.get(code) or error_classes.get(status_code, DominusError)
     raise error_class(message, status_code, details, endpoint)

{dominus_sdk_python-6.2.0 → dominus_sdk_python-6.3.0}/dominus/namespaces/stash.py

@@ -6,10 +6,18 @@ stores items in each project's ``stash.*`` schema and transparently falls
 back to a designated shared project on read.
 """
 from typing import Any, Dict, List, Optional, TYPE_CHECKING
+from urllib.parse import urlencode
 
 if TYPE_CHECKING:
     from ..start import Dominus
 
+BookmarkRef = Dict[str, Any]
+WatcherRef = Dict[str, Any]
+
+
+def _facade_query(*, env: str, kind: str, scope: str, key: str) -> str:
+    return urlencode({"env": env, "kind": kind, "scope": scope, "key": key})
+
 
 class StashNamespace:
     """
@@ -273,3 +281,155 @@ class StashNamespace:
             body=body,
             use_gateway=True,
         )
+
+    async def bookmark(
+        self,
+        *,
+        env: str,
+        kind: str,
+        scope: str,
+        key: str,
+        name: str,
+        version_ref: str,
+        timeout: float = 30.0,
+    ) -> BookmarkRef:
+        """Create or update a named bookmark for a stash artifact facade item."""
+        return await self._client._request(
+            endpoint="/svc/stash/bookmark",
+            method="POST",
+            body={
+                "env": env,
+                "kind": kind,
+                "scope": scope,
+                "key": key,
+                "name": name,
+                "version_ref": version_ref,
+            },
+            use_gateway=True,
+            timeout=timeout,
+        )
+
+    async def unbookmark(
+        self,
+        *,
+        env: str,
+        kind: str,
+        scope: str,
+        key: str,
+        name: str,
+        timeout: float = 30.0,
+    ) -> None:
+        """Remove a named bookmark from a stash artifact facade item."""
+        await self._client._request(
+            endpoint="/svc/stash/unbookmark",
+            method="POST",
+            body={
+                "env": env,
+                "kind": kind,
+                "scope": scope,
+                "key": key,
+                "name": name,
+            },
+            use_gateway=True,
+            timeout=timeout,
+        )
+        return None
+
+    async def watch(
+        self,
+        *,
+        env: str,
+        kind: str,
+        scope: str,
+        key: str,
+        watcher_name: str,
+        webhook_url: str,
+        timeout: float = 30.0,
+    ) -> WatcherRef:
+        """Create or update a webhook watcher for a stash artifact facade item."""
+        return await self._client._request(
+            endpoint="/svc/stash/watch",
+            method="POST",
+            body={
+                "env": env,
+                "kind": kind,
+                "scope": scope,
+                "key": key,
+                "watcher_name": watcher_name,
+                "webhook_url": webhook_url,
+            },
+            use_gateway=True,
+            timeout=timeout,
+        )
+
+    async def unwatch(
+        self,
+        *,
+        env: str,
+        kind: str,
+        scope: str,
+        key: str,
+        watcher_name: str,
+        timeout: float = 30.0,
+    ) -> None:
+        """Remove a webhook watcher from a stash artifact facade item."""
+        await self._client._request(
+            endpoint="/svc/stash/unwatch",
+            method="POST",
+            body={
+                "env": env,
+                "kind": kind,
+                "scope": scope,
+                "key": key,
+                "watcher_name": watcher_name,
+            },
+            use_gateway=True,
+            timeout=timeout,
+        )
+        return None
+
+    async def list_bookmarks(
+        self,
+        *,
+        env: str,
+        kind: str,
+        scope: str,
+        key: str,
+        timeout: float = 30.0,
+    ) -> List[BookmarkRef]:
+        """List bookmark refs for a stash artifact facade item."""
+        result = await self._client._request(
+            endpoint=f"/svc/stash/bookmark/list?{_facade_query(env=env, kind=kind, scope=scope, key=key)}",
+            method="GET",
+            use_gateway=True,
+            timeout=timeout,
+        )
+        if isinstance(result, list):
+            return result
+        if isinstance(result, dict):
+            bookmarks = result.get("bookmarks")
+            return bookmarks if isinstance(bookmarks, list) else []
+        return []
+
+    async def list_watchers(
+        self,
+        *,
+        env: str,
+        kind: str,
+        scope: str,
+        key: str,
+        timeout: float = 30.0,
+    ) -> List[WatcherRef]:
+        """List watcher refs for a stash artifact facade item."""
+        result = await self._client._request(
+            endpoint=f"/svc/stash/watch/list?{_facade_query(env=env, kind=kind, scope=scope, key=key)}",
+            method="GET",
+            use_gateway=True,
+            timeout=timeout,
+        )
+        if isinstance(result, list):
+            return result
+        if isinstance(result, dict):
+            watchers = result.get("watchers")
+            return watchers if isinstance(watchers, list) else []
+        return []

{dominus_sdk_python-6.2.0 → dominus_sdk_python-6.3.0}/dominus_sdk_python.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: dominus-sdk-python
-Version: 6.2.0
+Version: 6.3.0
 Summary: Python SDK for the Dominus gateway-first platform
 Author-email: CareBridge Systems <dev@carebridge.io>
 License-Expression: LicenseRef-Proprietary

{dominus_sdk_python-6.2.0 → dominus_sdk_python-6.3.0}/dominus_sdk_python.egg-info/SOURCES.txt

@@ -62,6 +62,7 @@ tests/test_public_exports.py
 tests/test_publisher_namespace.py
 tests/test_recipes_namespace.py
 tests/test_recipes_stash_routing.py
+tests/test_stash_artifact_facade.py
 tests/test_transport_compat.py
 tests/test_workflow_lifecycle.py
 tests/test_workflow_refs.py

{dominus_sdk_python-6.2.0 → dominus_sdk_python-6.3.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "dominus-sdk-python"
-version = "6.2.0"
+version = "6.3.0"
 description = "Python SDK for the Dominus gateway-first platform"
 readme = "README.md"
 license = "LicenseRef-Proprietary"

dominus_sdk_python-6.3.0/tests/test_stash_artifact_facade.py

@@ -0,0 +1,355 @@
+import pytest
+
+import dominus.start as start_module
+
+
+@pytest.fixture()
+def sdk(monkeypatch):
+    monkeypatch.setattr(start_module, "_VALIDATION_ERROR", None)
+    monkeypatch.setattr(start_module, "_TOKEN", "a" * 64)
+    monkeypatch.setattr(start_module, "_VALIDATED", False)
+    monkeypatch.setattr(start_module, "_BASE_URL", "https://gateway.example")
+    monkeypatch.setattr(start_module, "_GATEWAY_URL", "https://gateway.example")
+    return start_module.Dominus()
+
+
+@pytest.mark.asyncio
+async def test_bookmark_posts_to_stash_facade(monkeypatch, sdk):
+    calls = []
+
+    async def fake_request(**kwargs):
+        calls.append(kwargs)
+        return {
+            "name": "latest",
+            "version_ref": "v3",
+            "version": 3,
+            "hash": "sha256:bookmark",
+            "sticky_retention": None,
+            "ttl_seconds": None,
+            "expires_at": None,
+            "changed_since_bookmark": False,
+            "content_available": True,
+        }
+
+    monkeypatch.setattr(sdk, "_request", fake_request)
+
+    result = await sdk.stash.bookmark(
+        env="production",
+        kind="artifact",
+        scope="self",
+        key="my-key",
+        name="latest",
+        version_ref="v3",
+    )
+
+    assert result == {
+        "name": "latest",
+        "version_ref": "v3",
+        "version": 3,
+        "hash": "sha256:bookmark",
+        "sticky_retention": None,
+        "ttl_seconds": None,
+        "expires_at": None,
+        "changed_since_bookmark": False,
+        "content_available": True,
+    }
+    assert calls == [
+        {
+            "endpoint": "/svc/stash/bookmark",
+            "method": "POST",
+            "body": {
+                "env": "production",
+                "kind": "artifact",
+                "scope": "self",
+                "key": "my-key",
+                "name": "latest",
+                "version_ref": "v3",
+            },
+            "use_gateway": True,
+            "timeout": 30.0,
+        }
+    ]
+
+
+@pytest.mark.asyncio
+async def test_unbookmark_posts_to_stash_facade(monkeypatch, sdk):
+    calls = []
+
+    async def fake_request(**kwargs):
+        calls.append(kwargs)
+        return {"deleted": True}
+
+    monkeypatch.setattr(sdk, "_request", fake_request)
+
+    result = await sdk.stash.unbookmark(
+        env="production",
+        kind="artifact",
+        scope="self",
+        key="my-key",
+        name="latest",
+    )
+
+    assert result is None
+    assert calls == [
+        {
+            "endpoint": "/svc/stash/unbookmark",
+            "method": "POST",
+            "body": {
+                "env": "production",
+                "kind": "artifact",
+                "scope": "self",
+                "key": "my-key",
+                "name": "latest",
+            },
+            "use_gateway": True,
+            "timeout": 30.0,
+        }
+    ]
+
+
+@pytest.mark.asyncio
+async def test_watch_posts_to_stash_facade(monkeypatch, sdk):
+    calls = []
+
+    async def fake_request(**kwargs):
+        calls.append(kwargs)
+        return {
+            "watcher_name": "notify-reader",
+            "webhook_url": "https://hooks.example/stash",
+            "status": "active",
+            "created_at": "2026-06-26T12:00:00Z",
+        }
+
+    monkeypatch.setattr(sdk, "_request", fake_request)
+
+    result = await sdk.stash.watch(
+        env="production",
+        kind="artifact",
+        scope="self",
+        key="my-key",
+        watcher_name="notify-reader",
+        webhook_url="https://hooks.example/stash",
+    )
+
+    assert result == {
+        "watcher_name": "notify-reader",
+        "webhook_url": "https://hooks.example/stash",
+        "status": "active",
+        "created_at": "2026-06-26T12:00:00Z",
+    }
+    assert calls == [
+        {
+            "endpoint": "/svc/stash/watch",
+            "method": "POST",
+            "body": {
+                "env": "production",
+                "kind": "artifact",
+                "scope": "self",
+                "key": "my-key",
+                "watcher_name": "notify-reader",
+                "webhook_url": "https://hooks.example/stash",
+            },
+            "use_gateway": True,
+            "timeout": 30.0,
+        }
+    ]
+
+
+@pytest.mark.asyncio
+async def test_unwatch_posts_to_stash_facade(monkeypatch, sdk):
+    calls = []
+
+    async def fake_request(**kwargs):
+        calls.append(kwargs)
+        return {"deleted": True}
+
+    monkeypatch.setattr(sdk, "_request", fake_request)
+
+    result = await sdk.stash.unwatch(
+        env="production",
+        kind="artifact",
+        scope="self",
+        key="my-key",
+        watcher_name="notify-reader",
+    )
+
+    assert result is None
+    assert calls == [
+        {
+            "endpoint": "/svc/stash/unwatch",
+            "method": "POST",
+            "body": {
+                "env": "production",
+                "kind": "artifact",
+                "scope": "self",
+                "key": "my-key",
+                "watcher_name": "notify-reader",
+            },
+            "use_gateway": True,
+            "timeout": 30.0,
+        }
+    ]
+
+
+@pytest.mark.asyncio
+async def test_list_bookmarks_gets_stash_facade(monkeypatch, sdk):
+    calls = []
+    bookmarks = [
+        {
+            "name": "latest",
+            "version_ref": "v3",
+            "version": 3,
+            "hash": "sha256:bookmark",
+        }
+    ]
+
+    async def fake_request(**kwargs):
+        calls.append(kwargs)
+        return bookmarks
+
+    monkeypatch.setattr(sdk, "_request", fake_request)
+
+    result = await sdk.stash.list_bookmarks(
+        env="production",
+        kind="artifact",
+        scope="self",
+        key="my-key",
+    )
+
+    assert result == bookmarks
+    assert calls == [
+        {
+            "endpoint": "/svc/stash/bookmark/list?env=production&kind=artifact&scope=self&key=my-key",
+            "method": "GET",
+            "use_gateway": True,
+            "timeout": 30.0,
+        }
+    ]
+
+
+@pytest.mark.asyncio
+async def test_list_watchers_gets_stash_facade(monkeypatch, sdk):
+    calls = []
+    watchers = [
+        {
+            "watcher_name": "notify-reader",
+            "webhook_url": "https://hooks.example/stash",
+            "status": "active",
+        }
+    ]
+
+    async def fake_request(**kwargs):
+        calls.append(kwargs)
+        return watchers
+
+    monkeypatch.setattr(sdk, "_request", fake_request)
+
+    result = await sdk.stash.list_watchers(
+        env="production",
+        kind="artifact",
+        scope="self",
+        key="my-key",
+    )
+
+    assert result == watchers
+    assert calls == [
+        {
+            "endpoint": "/svc/stash/watch/list?env=production&kind=artifact&scope=self&key=my-key",
+            "method": "GET",
+            "use_gateway": True,
+            "timeout": 30.0,
+        }
+    ]
+
+
+def test_stash_facade_error_codes_map_to_public_exceptions():
+    from dominus import (
+        StashBookmarkArtifactNotFound,
+        StashBookmarkDuplicateName,
+        StashBookmarkInvalidVersionRef,
+        StashBookmarkUpstreamRejected,
+        StashWatchInvalidWebhookUrl,
+        StashWatchNotFound,
+        StashWatchUpstreamRejected,
+    )
+    from dominus.errors import raise_for_status
+
+    cases = [
+        (404, "stash.bookmark.artifact_not_found", StashBookmarkArtifactNotFound),
+        (400, "stash.bookmark.invalid_version_ref", StashBookmarkInvalidVersionRef),
+        (409, "stash.bookmark.duplicate_name", StashBookmarkDuplicateName),
+        (502, "stash.bookmark.upstream_rejected", StashBookmarkUpstreamRejected),
+        (400, "stash.watch.invalid_webhook_url", StashWatchInvalidWebhookUrl),
+        (502, "stash.watch.upstream_rejected", StashWatchUpstreamRejected),
+        (404, "stash.watch.not_found", StashWatchNotFound),
+    ]
+
+    for status_code, code, error_class in cases:
+        with pytest.raises(error_class) as exc_info:
+            raise_for_status(
+                status_code,
+                "stash facade failed",
+                {"code": code, "category": "validation"},
+                "/svc/stash/example",
+            )
+
+        assert exc_info.value.code == code
+        assert exc_info.value.endpoint == "/svc/stash/example"
+
+
+@pytest.mark.asyncio
+async def test_bookmark_artifact_not_found_raises_typed_exception(monkeypatch, sdk):
+    from dominus import StashBookmarkArtifactNotFound
+    from dominus.errors import raise_for_status
+
+    async def fake_request(**kwargs):
+        raise_for_status(
+            404,
+            "Artifact not found for bookmark operation",
+            {"code": "stash.bookmark.artifact_not_found", "category": "not_found"},
+            kwargs["endpoint"],
+        )
+
+    monkeypatch.setattr(sdk, "_request", fake_request)
+
+    with pytest.raises(StashBookmarkArtifactNotFound) as exc_info:
+        await sdk.stash.bookmark(
+            env="production",
+            kind="artifact",
+            scope="self",
+            key="my-key",
+            name="latest",
+            version_ref="v3",
+        )
+
+    assert exc_info.value.code == "stash.bookmark.artifact_not_found"
+    assert exc_info.value.endpoint == "/svc/stash/bookmark"
+
+
+@pytest.mark.asyncio
+async def test_watch_invalid_webhook_url_raises_typed_exception(monkeypatch, sdk):
+    from dominus import StashWatchInvalidWebhookUrl
+    from dominus.errors import raise_for_status
+
+    async def fake_request(**kwargs):
+        raise_for_status(
+            400,
+            "webhook_url must be an absolute http(s) URL",
+            {"code": "stash.watch.invalid_webhook_url", "category": "validation"},
+            kwargs["endpoint"],
+        )
+
+    monkeypatch.setattr(sdk, "_request", fake_request)
+
+    with pytest.raises(StashWatchInvalidWebhookUrl) as exc_info:
+        await sdk.stash.watch(
+            env="production",
+            kind="artifact",
+            scope="self",
+            key="my-key",
+            watcher_name="notify-reader",
+            webhook_url="not-a-url",
+        )
+
+    assert exc_info.value.code == "stash.watch.invalid_webhook_url"
+    assert exc_info.value.endpoint == "/svc/stash/watch"