dominus-sdk-python 9.0.11__tar.gz → 9.0.12__tar.gz

{dominus_sdk_python-9.0.11 → dominus_sdk_python-9.0.12}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: dominus-sdk-python
-Version: 9.0.11
+Version: 9.0.12
 Summary: Python SDK for the Dominus gateway-first platform
 Author-email: CareBridge Systems <dev@carebridge.io>
 License-Expression: LicenseRef-Proprietary
@@ -48,7 +48,7 @@ cleanup audit is `docs/janitor/2026-09-14-1300-sdk-python-cleanup-audit.md`.
 - Gateway-scoped client mode for MCP and other user-JWT sessions
 - Transport compatibility for wrapped `{success,data}` responses and unwrapped Warden/control-plane success objects
 - Local helpers for JWT verification, trace propagation, retries, and console capture
-- Current package version: `9.0.11`
+- Current package version: `9.0.12`
 
 ## Install
 

{dominus_sdk_python-9.0.11 → dominus_sdk_python-9.0.12}/README.md

@@ -15,7 +15,7 @@ cleanup audit is `docs/janitor/2026-09-14-1300-sdk-python-cleanup-audit.md`.
 - Gateway-scoped client mode for MCP and other user-JWT sessions
 - Transport compatibility for wrapped `{success,data}` responses and unwrapped Warden/control-plane success objects
 - Local helpers for JWT verification, trace propagation, retries, and console capture
-- Current package version: `9.0.11`
+- Current package version: `9.0.12`
 
 ## Install
 

{dominus_sdk_python-9.0.11 → dominus_sdk_python-9.0.12}/dominus/__init__.py

@@ -121,6 +121,7 @@ from .namespaces.platform import PlatformNamespace
 from .namespaces.coder import CoderNamespace
 from .namespaces.publisher import PublisherNamespace
 from .namespaces.stash import StashNamespace, StashTablesNamespace
+from .namespaces.usage import UsageNamespace
 
 # Export AI namespace for agent-runtime operations
 from .namespaces.ai import (
@@ -190,7 +191,7 @@ from .errors import (
     TimeoutError as DominusTimeoutError,
 )
 
-__version__ = "9.0.11"
+__version__ = "9.0.12"
 __all__ = [
     # Main SDK instance
     "dominus",
@@ -249,6 +250,7 @@ __all__ = [
     "PublisherNamespace",
     "StashNamespace",
     "StashTablesNamespace",
+    "UsageNamespace",
     # AI namespace for agent-runtime operations
     "AiNamespace",
     "RagSubNamespace",

dominus_sdk_python-9.0.12/dominus/helpers/auth.py

@@ -0,0 +1,57 @@
+"""
+Token resolution helper.
+
+Handles resolution of authentication token from environment variables.
+No hardcoded tokens supported - environment variable only.
+"""
+import os
+from typing import Optional
+
+
+def _resolve_token() -> Optional[str]:
+    """
+    Resolve auth token from environment variable.
+
+    Precedence: DOMINUS_USER_TOKEN outranks DOMINUS_TOKEN. This is intentional
+    (the README quick start is a gateway user-token flow), but it means an
+    ambient operator token silently shadows a project PSK. Callers that intend
+    project-PSK auth must scrub DOMINUS_USER_TOKEN (and DOMINUS_MCP_USER_TOKEN)
+    from the environment before importing this package.
+
+    Note: When fetching from Infisical via Sovereign, the secret is stored as
+    PROVISION_DOMINUS_TOKEN but should be set as DOMINUS_TOKEN in environment.
+    The PROVISION_ prefix is dropped when setting environment variables.
+
+    Returns:
+        Token string or None if not set
+    """
+    return os.getenv("DOMINUS_USER_TOKEN") or os.getenv("DOMINUS_TOKEN")
+
+
+def _shadowed_token_hint(token: Optional[str]) -> Optional[str]:
+    """
+    Diagnose a token that may have been shadowed by environment precedence.
+
+    Returns a message naming BOTH variables when, and only when, the ambiguity
+    is real: DOMINUS_USER_TOKEN and DOMINUS_TOKEN are both set AND ``token`` is
+    the shadowing value that precedence selected. A caller-supplied token that
+    is not the environment's chosen value was never ambiguous, so it returns
+    None, as does any environment where only one variable is set.
+
+    Args:
+        token: The token an auth attempt actually used
+
+    Returns:
+        Diagnostic message, or None when there is nothing ambiguous to report
+    """
+    user_token = os.getenv("DOMINUS_USER_TOKEN")
+    psk_token = os.getenv("DOMINUS_TOKEN")
+    if not user_token or not psk_token or token != user_token:
+        return None
+    return (
+        "DOMINUS_USER_TOKEN outranks DOMINUS_TOKEN (dominus/helpers/auth.py) and "
+        "both are set in this environment, so this attempt authenticated with "
+        "DOMINUS_USER_TOKEN. If you intended project-PSK auth, unset "
+        "DOMINUS_USER_TOKEN (and DOMINUS_MCP_USER_TOKEN) before importing the "
+        "SDK and retry."
+    )

{dominus_sdk_python-9.0.11 → dominus_sdk_python-9.0.12}/dominus/helpers/core.py

@@ -11,6 +11,7 @@ import json
 import time
 from typing import Any, Optional
 
+from .auth import _shadowed_token_hint
 from .cache import dominus_cache, gateway_circuit_breaker, exponential_backoff_with_jitter
 
 # Max retries for HTTP requests (reduced from implicit to explicit)
@@ -349,6 +350,13 @@ def is_jwt_valid(jwt_token: str) -> bool:
         return False
 
 
+def _mint_failure_message(message: str, shadow_hint: Optional[str]) -> str:
+    """Append the token-shadowing diagnostic to a failed-mint message."""
+    if not shadow_hint:
+        return message
+    return f"{message}\n{shadow_hint}"
+
+
 async def _get_service_jwt(psk_token: str, base_url: str) -> str:
     """
     Get service JWT by calling gateway /jwt/mint with PSK.
@@ -392,6 +400,10 @@ async def _get_service_jwt(psk_token: str, base_url: str) -> str:
     body_json = {"method": "auth.self", "params": {}}
     body_b64 = _b64_encode(body_json)
 
+    # A rejected mint is indistinguishable from a bad PSK when an ambient
+    # DOMINUS_USER_TOKEN shadowed the intended project PSK at import.
+    shadow_hint = _shadowed_token_hint(psk_token)
+
     # Retry loop for JWT minting
     JWT_MINT_RETRIES = 3
     last_error = None
@@ -419,7 +431,9 @@ async def _get_service_jwt(psk_token: str, base_url: str) -> str:
                 if not result.get("success"):
                     error_msg = result.get("error", "Unknown auth error")
                     gateway_circuit_breaker.record_failure()
-                    raise RuntimeError(f"Auth error: {error_msg}")
+                    raise RuntimeError(
+                        _mint_failure_message(f"Auth error: {error_msg}", shadow_hint)
+                    )
 
                 data = result.get("data", {})
                 jwt = data.get("access_token") or data.get("token")
@@ -465,7 +479,9 @@ async def _get_service_jwt(psk_token: str, base_url: str) -> str:
                 raise RuntimeError(f"Failed to get JWT: {e}") from e
             # For other errors, we've already handled retries in the status check above
             gateway_circuit_breaker.record_failure()
-            raise RuntimeError(f"Failed to get JWT: {e}") from e
+            raise RuntimeError(
+                _mint_failure_message(f"Failed to get JWT: {e}", shadow_hint)
+            ) from e
 
     # Should not reach here, but just in case
     gateway_circuit_breaker.record_failure()

{dominus_sdk_python-9.0.11 → dominus_sdk_python-9.0.12}/dominus/namespaces/__init__.py

@@ -28,6 +28,7 @@ from .platform import PlatformNamespace
 from .coder import CoderNamespace
 from .publisher import PublisherNamespace
 from .stash import StashNamespace, StashTablesNamespace
+from .usage import UsageNamespace
 from .ai import (
     AiNamespace,
     RagSubNamespace,
@@ -65,6 +66,7 @@ __all__ = [
     "PublisherNamespace",
     "StashNamespace",
     "StashTablesNamespace",
+    "UsageNamespace",
     "AiNamespace",
     "RagSubNamespace",
     "ArtifactsSubNamespace",

dominus_sdk_python-9.0.12/dominus/namespaces/usage.py

@@ -0,0 +1,214 @@
+"""
+Usage Namespace - Dominus consumption and provider-cost reporting.
+
+Canonical SDK entry point for the dominus-usage service's authorized read
+surface: summary, evidence, coverage, and explain. All four route through
+the gateway (``use_gateway=True``), which maps ``/api/usage/*`` ->
+``/svc/usage/*`` upstream to dominus-usage.
+
+This namespace is a thin pass-through: it never converts quantities/amounts
+to float, never infers a default window or grouping (the service applies
+last-7-days / meter+project+environment+logical_service when omitted), and
+never adds a token of its own. An explicitly minted human bearer reaches
+Usage unchanged via the existing ``Dominus(gateway_user_token=...)``
+constructor behavior, exactly like ``dominus.authority.*``.
+"""
+from __future__ import annotations
+
+from typing import Any, Dict, Optional, Sequence, TYPE_CHECKING, Union
+from urllib.parse import urlencode
+
+if TYPE_CHECKING:
+    from ..start import Dominus
+
+
+def _query_string(params: Dict[str, Any]) -> str:
+    """Build a ``?...`` query string, repeating the key for list/tuple values."""
+    pairs: list[tuple[str, str]] = []
+    for key, value in params.items():
+        if value is None or value == "":
+            continue
+        if isinstance(value, (list, tuple)):
+            for item in value:
+                if item is None or item == "":
+                    continue
+                pairs.append((key, str(item)))
+        else:
+            pairs.append((key, str(value)))
+    if not pairs:
+        return ""
+    return "?" + urlencode(pairs)
+
+
+class UsageNamespace:
+    """
+    Usage service namespace: typed consumption and provider-cost reads.
+
+    Usage::
+
+        await dominus.usage.summary(since="2026-09-01T00:00:00Z", meter="ai.tokens.input")
+        await dominus.usage.evidence(project_id="proj_123", limit=100)
+        await dominus.usage.coverage()
+        await dominus.usage.explain(observation_id="obs_123")
+    """
+
+    def __init__(self, client: "Dominus"):
+        self._client = client
+
+    async def _get(self, endpoint: str, *, timeout: float = 30.0) -> Dict[str, Any]:
+        return await self._client._request(
+            endpoint=endpoint,
+            method="GET",
+            use_gateway=True,
+            timeout=timeout,
+        )
+
+    async def summary(
+        self,
+        *,
+        since: Optional[str] = None,
+        until: Optional[str] = None,
+        group_by: Optional[Union[str, Sequence[str]]] = None,
+        project_id: Optional[str] = None,
+        environment: Optional[str] = None,
+        logical_service: Optional[str] = None,
+        family_root_id: Optional[str] = None,
+        meter: Optional[str] = None,
+        provider: Optional[str] = None,
+        timeout: float = 30.0,
+    ) -> Dict[str, Any]:
+        """Unit-aware usage rows plus distinct provider-reported/estimated cost.
+
+        ``GET /api/usage/summary``. Omitting ``since``/``until`` uses the
+        service's last-7-days default; omitting ``group_by`` uses its default
+        grouping. Quantities/amounts are returned as decimal strings, never
+        converted to float.
+        """
+        qs = _query_string(
+            {
+                "since": since,
+                "until": until,
+                "group_by": group_by,
+                "project_id": project_id,
+                "environment": environment,
+                "logical_service": logical_service,
+                "family_root_id": family_root_id,
+                "meter": meter,
+                "provider": provider,
+            }
+        )
+        return await self._get(f"/api/usage/summary{qs}", timeout=timeout)
+
+    async def evidence(
+        self,
+        *,
+        since: Optional[str] = None,
+        until: Optional[str] = None,
+        project_id: Optional[str] = None,
+        environment: Optional[str] = None,
+        logical_service: Optional[str] = None,
+        family_root_id: Optional[str] = None,
+        meter: Optional[str] = None,
+        provider: Optional[str] = None,
+        limit: Optional[int] = None,
+        cursor: Optional[str] = None,
+        timeout: float = 30.0,
+    ) -> Dict[str, Any]:
+        """Cursor-paginated observation/provider-source evidence.
+
+        ``GET /api/usage/evidence``. ``limit`` defaults to 100 and is bounded
+        to 500 server-side; pass the response's ``next_cursor`` back in to
+        page forward.
+        """
+        qs = _query_string(
+            {
+                "since": since,
+                "until": until,
+                "project_id": project_id,
+                "environment": environment,
+                "logical_service": logical_service,
+                "family_root_id": family_root_id,
+                "meter": meter,
+                "provider": provider,
+                "limit": limit,
+                "cursor": cursor,
+            }
+        )
+        return await self._get(f"/api/usage/evidence{qs}", timeout=timeout)
+
+    async def coverage(
+        self,
+        *,
+        since: Optional[str] = None,
+        until: Optional[str] = None,
+        project_id: Optional[str] = None,
+        environment: Optional[str] = None,
+        logical_service: Optional[str] = None,
+        family_root_id: Optional[str] = None,
+        meter: Optional[str] = None,
+        provider: Optional[str] = None,
+        timeout: float = 30.0,
+    ) -> Dict[str, Any]:
+        """Registered meter/source coverage, freshness, and gap reasons.
+
+        ``GET /api/usage/coverage``. Never reports unsupported capture as
+        complete; ``gaps`` names each unavailable reason explicitly.
+        """
+        qs = _query_string(
+            {
+                "since": since,
+                "until": until,
+                "project_id": project_id,
+                "environment": environment,
+                "logical_service": logical_service,
+                "family_root_id": family_root_id,
+                "meter": meter,
+                "provider": provider,
+            }
+        )
+        return await self._get(f"/api/usage/coverage{qs}", timeout=timeout)
+
+    async def explain(
+        self,
+        *,
+        observation_id: Optional[str] = None,
+        operation_id: Optional[str] = None,
+        since: Optional[str] = None,
+        until: Optional[str] = None,
+        project_id: Optional[str] = None,
+        environment: Optional[str] = None,
+        logical_service: Optional[str] = None,
+        family_root_id: Optional[str] = None,
+        meter: Optional[str] = None,
+        timeout: float = 30.0,
+    ) -> Dict[str, Any]:
+        """Explanation linking permitted observations, attempts, and cost basis.
+
+        ``GET /api/usage/explain``. Exactly one of ``observation_id`` or
+        ``operation_id`` must be supplied; supplying both (or neither) is
+        rejected locally before the request is sent, matching the service's
+        own ambiguous-selector rejection. The remaining filters narrow which
+        observations can match an ``operation_id`` lookup; they are inert for
+        an ``observation_id`` lookup, which the service resolves unfiltered.
+        """
+        if bool(observation_id) == bool(operation_id):
+            raise ValueError(
+                "usage.explain requires exactly one of observation_id or operation_id"
+            )
+        qs = _query_string(
+            {
+                "observation_id": observation_id,
+                "operation_id": operation_id,
+                "since": since,
+                "until": until,
+                "project_id": project_id,
+                "environment": environment,
+                "logical_service": logical_service,
+                "family_root_id": family_root_id,
+                "meter": meter,
+            }
+        )
+        return await self._get(f"/api/usage/explain{qs}", timeout=timeout)
+
+
+__all__ = ["UsageNamespace"]

{dominus_sdk_python-9.0.11 → dominus_sdk_python-9.0.12}/dominus/start.py

@@ -196,6 +196,10 @@ class Dominus:
         from .namespaces.recipes import RecipesNamespace
         self.recipes = RecipesNamespace(self)
 
+        # Usage service (dominus-usage; consumption and provider-cost reports)
+        from .namespaces.usage import UsageNamespace
+        self.usage = UsageNamespace(self)
+
         # Cache for JWT public key
         self._public_key_cache = None
 

{dominus_sdk_python-9.0.11 → dominus_sdk_python-9.0.12}/dominus_sdk_python.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: dominus-sdk-python
-Version: 9.0.11
+Version: 9.0.12
 Summary: Python SDK for the Dominus gateway-first platform
 Author-email: CareBridge Systems <dev@carebridge.io>
 License-Expression: LicenseRef-Proprietary
@@ -48,7 +48,7 @@ cleanup audit is `docs/janitor/2026-09-14-1300-sdk-python-cleanup-audit.md`.
 - Gateway-scoped client mode for MCP and other user-JWT sessions
 - Transport compatibility for wrapped `{success,data}` responses and unwrapped Warden/control-plane success objects
 - Local helpers for JWT verification, trace propagation, retries, and console capture
-- Current package version: `9.0.11`
+- Current package version: `9.0.12`
 
 ## Install
 

{dominus_sdk_python-9.0.11 → dominus_sdk_python-9.0.12}/dominus_sdk_python.egg-info/SOURCES.txt

@@ -44,6 +44,7 @@ dominus/namespaces/secrets.py
 dominus/namespaces/secure.py
 dominus/namespaces/stash.py
 dominus/namespaces/sync.py
+dominus/namespaces/usage.py
 dominus/namespaces/warden.py
 dominus/namespaces/workflow.py
 dominus/services/__init__.py
@@ -76,7 +77,9 @@ tests/test_recipes_stash_routing.py
 tests/test_secrets_presence_contract.py
 tests/test_stash_artifact_facade.py
 tests/test_stash_tables_namespace.py
+tests/test_token_precedence.py
 tests/test_transport_compat.py
+tests/test_usage_namespace.py
 tests/test_version_consistency.py
 tests/test_workflow_lifecycle.py
 tests/test_workflow_refs.py

{dominus_sdk_python-9.0.11 → dominus_sdk_python-9.0.12}/pyproject.toml

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

dominus_sdk_python-9.0.12/tests/test_token_precedence.py

@@ -0,0 +1,174 @@
+"""Token precedence contract for ``DOMINUS_USER_TOKEN`` vs ``DOMINUS_TOKEN``.
+
+``DOMINUS_USER_TOKEN`` outranks ``DOMINUS_TOKEN`` by design (the README quick
+start is a user-token flow). The hazard is that the shadowing is silent: when an
+operator token is ambient and the caller intended project-PSK auth, a 401 reads
+exactly like a bad PSK. These tests lock the precedence itself as unchanged and
+assert that a failed mint names both variables so the shadowing is diagnosable
+from the error alone.
+"""
+import sys
+from pathlib import Path
+
+import httpx
+import pytest
+
+
+ROOT = Path(__file__).resolve().parents[1]
+if str(ROOT) not in sys.path:
+    sys.path.insert(0, str(ROOT))
+
+import dominus.helpers.auth as auth_module  # noqa: E402
+import dominus.helpers.core as core_module  # noqa: E402
+from dominus.helpers.auth import _resolve_token, _shadowed_token_hint  # noqa: E402
+
+
+USER_TOKEN = "u" * 64
+PROJECT_PSK = "p" * 64
+
+
+@pytest.fixture(autouse=True)
+def _clean_token_env(monkeypatch):
+    """No ambient token state leaks into, or out of, these tests."""
+    monkeypatch.delenv("DOMINUS_USER_TOKEN", raising=False)
+    monkeypatch.delenv("DOMINUS_TOKEN", raising=False)
+
+
+@pytest.fixture
+def _closed_breaker():
+    """Keep the shared gateway circuit breaker deterministic across tests."""
+    breaker = core_module.gateway_circuit_breaker
+    breaker._failure_count = 0
+    breaker._state = breaker.CLOSED
+    breaker._half_open_calls = 0
+    yield breaker
+
+
+# --- Precedence contract (must NOT change) ---------------------------------
+
+
+def test_resolve_token_prefers_user_token_when_both_set(monkeypatch):
+    monkeypatch.setenv("DOMINUS_USER_TOKEN", USER_TOKEN)
+    monkeypatch.setenv("DOMINUS_TOKEN", PROJECT_PSK)
+
+    assert _resolve_token() == USER_TOKEN
+
+
+def test_resolve_token_falls_back_to_project_psk(monkeypatch):
+    monkeypatch.setenv("DOMINUS_TOKEN", PROJECT_PSK)
+
+    assert _resolve_token() == PROJECT_PSK
+
+
+# --- Shadowing diagnostic ---------------------------------------------------
+
+
+def test_shadowed_token_hint_is_quiet_when_only_project_psk_is_set(monkeypatch):
+    monkeypatch.setenv("DOMINUS_TOKEN", PROJECT_PSK)
+
+    assert _shadowed_token_hint(PROJECT_PSK) is None
+
+
+def test_shadowed_token_hint_is_quiet_when_only_user_token_is_set(monkeypatch):
+    monkeypatch.setenv("DOMINUS_USER_TOKEN", USER_TOKEN)
+
+    assert _shadowed_token_hint(USER_TOKEN) is None
+
+
+def test_shadowed_token_hint_names_both_variables_when_user_token_shadows(monkeypatch):
+    monkeypatch.setenv("DOMINUS_USER_TOKEN", USER_TOKEN)
+    monkeypatch.setenv("DOMINUS_TOKEN", PROJECT_PSK)
+
+    hint = _shadowed_token_hint(USER_TOKEN)
+
+    assert hint is not None
+    assert "DOMINUS_USER_TOKEN" in hint
+    assert "DOMINUS_TOKEN" in hint
+
+
+def test_shadowed_token_hint_is_quiet_for_an_explicit_non_env_token(monkeypatch):
+    """A caller-supplied token was never ambiguous, so do not blame the env."""
+    monkeypatch.setenv("DOMINUS_USER_TOKEN", USER_TOKEN)
+    monkeypatch.setenv("DOMINUS_TOKEN", PROJECT_PSK)
+
+    assert _shadowed_token_hint(PROJECT_PSK) is None
+
+
+# --- Mint failure path ------------------------------------------------------
+
+
+class Fake401Response:
+    status_code = 401
+
+    def __init__(self):
+        self.text = ""
+
+    def raise_for_status(self):
+        raise httpx.HTTPStatusError(
+            "401 Unauthorized",
+            request=httpx.Request("POST", "https://gateway.example/jwt/mint"),
+            response=httpx.Response(401),
+        )
+
+
+class FakeAsyncClient:
+    def __init__(self, *args, **kwargs):
+        pass
+
+    async def __aenter__(self):
+        return self
+
+    async def __aexit__(self, exc_type, exc, tb):
+        return False
+
+    async def post(self, url, content=None):
+        return Fake401Response()
+
+
+@pytest.fixture
+def _minting_against_401(monkeypatch):
+    monkeypatch.setattr(core_module.httpx, "AsyncClient", FakeAsyncClient)
+    monkeypatch.setattr(
+        core_module, "get_gateway_url", lambda: "https://gateway.example", raising=False
+    )
+    monkeypatch.setattr(
+        core_module, "get_proxy_config", lambda: None, raising=False
+    )
+
+    async def _no_sleep(_seconds):
+        return None
+
+    monkeypatch.setattr(core_module.asyncio, "sleep", _no_sleep)
+
+    # The endpoint getters are imported inside the function body.
+    import dominus.config.endpoints as endpoints
+
+    monkeypatch.setattr(endpoints, "get_gateway_url", lambda: "https://gateway.example")
+    monkeypatch.setattr(endpoints, "get_proxy_config", lambda: None)
+
+
+@pytest.mark.asyncio
+async def test_mint_failure_names_both_variables_when_shadowed(
+    monkeypatch, _closed_breaker, _minting_against_401
+):
+    monkeypatch.setenv("DOMINUS_USER_TOKEN", USER_TOKEN)
+    monkeypatch.setenv("DOMINUS_TOKEN", PROJECT_PSK)
+
+    with pytest.raises(RuntimeError) as excinfo:
+        await core_module._get_service_jwt(USER_TOKEN, "https://gateway.example")
+
+    message = str(excinfo.value)
+    assert "DOMINUS_USER_TOKEN" in message
+    assert "DOMINUS_TOKEN" in message
+
+
+@pytest.mark.asyncio
+async def test_mint_failure_omits_hint_when_not_shadowed(
+    monkeypatch, _closed_breaker, _minting_against_401
+):
+    monkeypatch.setenv("DOMINUS_TOKEN", PROJECT_PSK)
+
+    with pytest.raises(RuntimeError) as excinfo:
+        await core_module._get_service_jwt(PROJECT_PSK, "https://gateway.example")
+
+    assert "DOMINUS_USER_TOKEN" not in str(excinfo.value)

dominus_sdk_python-9.0.12/tests/test_usage_namespace.py

@@ -0,0 +1,210 @@
+import pytest
+
+from dominus.namespaces.usage import UsageNamespace
+
+
+class FakeClient:
+    def __init__(self, response=None):
+        self.calls = []
+        self._response = response if response is not None else {"schema_version": 1}
+
+    async def _request(
+        self,
+        endpoint,
+        method="POST",
+        body=None,
+        user_token=None,
+        use_gateway=False,
+        timeout=30.0,
+        actor=None,
+        **kwargs,
+    ):
+        self.calls.append(
+            {
+                "endpoint": endpoint,
+                "method": method,
+                "body": body,
+                "user_token": user_token,
+                "use_gateway": use_gateway,
+                "timeout": timeout,
+            }
+        )
+        return self._response
+
+
+@pytest.mark.asyncio
+async def test_summary_defaults_send_no_query_string():
+    client = FakeClient()
+    usage = UsageNamespace(client)
+
+    await usage.summary()
+
+    assert client.calls == [
+        {
+            "endpoint": "/api/usage/summary",
+            "method": "GET",
+            "body": None,
+            "user_token": None,
+            "use_gateway": True,
+            "timeout": 30.0,
+        }
+    ]
+
+
+@pytest.mark.asyncio
+async def test_summary_builds_full_query_string_with_repeated_group_by():
+    client = FakeClient()
+    usage = UsageNamespace(client)
+
+    await usage.summary(
+        since="2026-09-01T00:00:00Z",
+        until="2026-09-08T00:00:00Z",
+        group_by=["meter", "project"],
+        project_id="proj_123",
+        environment="production",
+        logical_service="gateway",
+        family_root_id="fam_1",
+        meter="ai.tokens.input",
+        provider="anthropic",
+    )
+
+    assert client.calls[0]["endpoint"] == (
+        "/api/usage/summary?since=2026-09-01T00%3A00%3A00Z&until=2026-09-08T00%3A00%3A00Z"
+        "&group_by=meter&group_by=project&project_id=proj_123&environment=production"
+        "&logical_service=gateway&family_root_id=fam_1&meter=ai.tokens.input&provider=anthropic"
+    )
+    assert client.calls[0]["method"] == "GET"
+    assert client.calls[0]["use_gateway"] is True
+
+
+@pytest.mark.asyncio
+async def test_summary_accepts_single_group_by_string():
+    client = FakeClient()
+    usage = UsageNamespace(client)
+
+    await usage.summary(group_by="meter")
+
+    assert client.calls[0]["endpoint"] == "/api/usage/summary?group_by=meter"
+
+
+@pytest.mark.asyncio
+async def test_summary_never_converts_decimal_quantities_to_float():
+    client = FakeClient(
+        response={
+            "usage": [{"quantity": "12.345678901234567890", "unit": "tokens"}],
+            "provider_reported_cost": [{"amount": "0.010000000000000001", "currency": "USD"}],
+        }
+    )
+    usage = UsageNamespace(client)
+
+    result = await usage.summary()
+
+    assert isinstance(result["usage"][0]["quantity"], str)
+    assert result["usage"][0]["quantity"] == "12.345678901234567890"
+    assert isinstance(result["provider_reported_cost"][0]["amount"], str)
+    assert result["provider_reported_cost"][0]["amount"] == "0.010000000000000001"
+
+
+@pytest.mark.asyncio
+async def test_evidence_builds_pagination_query_string():
+    client = FakeClient()
+    usage = UsageNamespace(client)
+
+    await usage.evidence(project_id="proj_123", limit=250, cursor="cursor-abc")
+
+    assert client.calls[0]["endpoint"] == (
+        "/api/usage/evidence?project_id=proj_123&limit=250&cursor=cursor-abc"
+    )
+
+
+@pytest.mark.asyncio
+async def test_evidence_defaults_omit_limit_and_cursor_from_query_string():
+    client = FakeClient()
+    usage = UsageNamespace(client)
+
+    await usage.evidence()
+
+    assert client.calls[0]["endpoint"] == "/api/usage/evidence"
+
+
+@pytest.mark.asyncio
+async def test_coverage_builds_filtered_query_string():
+    client = FakeClient()
+    usage = UsageNamespace(client)
+
+    await usage.coverage(meter="ai.tokens.input", provider="openai")
+
+    assert client.calls[0]["endpoint"] == "/api/usage/coverage?meter=ai.tokens.input&provider=openai"
+
+
+@pytest.mark.asyncio
+async def test_explain_by_observation_id():
+    client = FakeClient()
+    usage = UsageNamespace(client)
+
+    await usage.explain(observation_id="obs_123")
+
+    assert client.calls[0]["endpoint"] == "/api/usage/explain?observation_id=obs_123"
+    assert client.calls[0]["method"] == "GET"
+
+
+@pytest.mark.asyncio
+async def test_explain_by_operation_id():
+    client = FakeClient()
+    usage = UsageNamespace(client)
+
+    await usage.explain(operation_id="op_456")
+
+    assert client.calls[0]["endpoint"] == "/api/usage/explain?operation_id=op_456"
+
+
+@pytest.mark.asyncio
+async def test_explain_by_operation_id_narrows_with_scope_filters():
+    client = FakeClient()
+    usage = UsageNamespace(client)
+
+    await usage.explain(
+        operation_id="op_456",
+        project_id="proj_123",
+        environment="production",
+        logical_service="gateway",
+        family_root_id="fam_1",
+        meter="ai.tokens.input",
+    )
+
+    assert client.calls[0]["endpoint"] == (
+        "/api/usage/explain?operation_id=op_456&project_id=proj_123&environment=production"
+        "&logical_service=gateway&family_root_id=fam_1&meter=ai.tokens.input"
+    )
+
+
+@pytest.mark.asyncio
+async def test_explain_rejects_both_selectors_without_a_request():
+    client = FakeClient()
+    usage = UsageNamespace(client)
+
+    with pytest.raises(ValueError):
+        await usage.explain(observation_id="obs_123", operation_id="op_456")
+
+    assert client.calls == []
+
+
+@pytest.mark.asyncio
+async def test_explain_rejects_neither_selector_without_a_request():
+    client = FakeClient()
+    usage = UsageNamespace(client)
+
+    with pytest.raises(ValueError):
+        await usage.explain()
+
+    assert client.calls == []
+
+
+@pytest.mark.asyncio
+async def test_singleton_exposes_usage_namespace():
+    from dominus import dominus
+
+    assert callable(dominus.usage.summary)
+    assert callable(dominus.usage.evidence)
+    assert callable(dominus.usage.coverage)
+    assert callable(dominus.usage.explain)

dominus_sdk_python-9.0.11/dominus/helpers/auth.py

@@ -1,23 +0,0 @@
-"""
-Token resolution helper.
-
-Handles resolution of authentication token from environment variables.
-No hardcoded tokens supported - environment variable only.
-"""
-import os
-from typing import Optional
-
-
-def _resolve_token() -> Optional[str]:
-    """
-    Resolve auth token from environment variable.
-
-    Note: When fetching from Infisical via Sovereign, the secret is stored as
-    PROVISION_DOMINUS_TOKEN but should be set as DOMINUS_TOKEN in environment.
-    The PROVISION_ prefix is dropped when setting environment variables.
-
-    Returns:
-        Token string or None if not set
-    """
-    return os.getenv("DOMINUS_USER_TOKEN") or os.getenv("DOMINUS_TOKEN")
-