dominusnode 2.0.0__py3-none-any.whl

dominusnode/__init__.py

@@ -0,0 +1,45 @@
+"""Official DominusNode SDK for Python: AI-agent relay network (proxy, nodes, credits, payouts)."""
+
+from .client import AsyncDominusNodeClient, DominusNodeClient
+from .constants import (
+    DEFAULT_BASE_URL,
+    DEFAULT_HTTP_PROXY_PORT,
+    DEFAULT_PROXY_HOST,
+    DEFAULT_SOCKS5_PROXY_PORT,
+    MAX_AMOUNT_CENTS,
+    MAX_RESPONSE_BYTES,
+    SDK_VERSION,
+    USER_AGENT,
+)
+from .errors import (
+    AuthenticationError,
+    AuthorizationError,
+    ConflictError,
+    DominusNodeError,
+    InsufficientBalanceError,
+    NetworkError,
+    NotFoundError,
+    ProtocolError,
+    ProxyError,
+    RateLimitError,
+    ServerError,
+    ValidationError,
+    scrub_credentials,
+)
+from .messages import build_attestation_message, build_payout_wallet_message, build_withdraw_message
+from .proxy_fetch import GatewayTls, ProxyFetchResponse, build_proxy_username
+from .secret import Secret, json_default
+from .signer import Signer
+from .ssrf import is_private_ip, validate_target_url
+
+__version__ = SDK_VERSION
+
+__all__ = [
+    "DominusNodeClient", "AsyncDominusNodeClient", "Signer", "Secret", "json_default",
+    "build_proxy_username", "ProxyFetchResponse", "GatewayTls", "is_private_ip", "validate_target_url",
+    "build_attestation_message", "build_payout_wallet_message", "build_withdraw_message",
+    "DominusNodeError", "AuthenticationError", "AuthorizationError", "RateLimitError", "InsufficientBalanceError",
+    "ValidationError", "NotFoundError", "ConflictError", "ServerError", "NetworkError", "ProtocolError", "ProxyError",
+    "scrub_credentials", "SDK_VERSION", "USER_AGENT", "DEFAULT_BASE_URL", "DEFAULT_PROXY_HOST",
+    "DEFAULT_HTTP_PROXY_PORT", "DEFAULT_SOCKS5_PROXY_PORT", "MAX_RESPONSE_BYTES", "MAX_AMOUNT_CENTS", "__version__",
+]

dominusnode/_ops.py

@@ -0,0 +1,122 @@
+"""Sans-I/O core shared by the sync and async clients (internal).
+
+Each resource method is written once as a generator that yields operations
+(an API ``Request``, a ``Sign`` call or a blocking ``Call``) and receives their
+results. ``drive_sync`` / ``drive_async`` execute those operations, so the sync
+and async clients expose identical behaviour from a single implementation.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import functools
+import inspect
+from dataclasses import dataclass
+from typing import Any, Callable, Dict, Generator, Tuple, Type, TypeVar
+
+from .errors import ProtocolError
+from .http_client import AsyncHttpClient, Request, SyncHttpClient
+
+Op = Any
+Gen = Generator[Op, Any, Any]
+
+
+@dataclass
+class Sign:
+    signer: Any
+    message: str
+
+
+@dataclass
+class Call:
+    """Blocking work (PoW, socket I/O). Sync: called inline. Async: run in a worker thread."""
+
+    fn: Callable[..., Any]
+    args: Tuple[Any, ...] = ()
+
+
+def _exec_sync(http: SyncHttpClient, op: Op) -> Any:
+    if isinstance(op, Request):
+        return http.request(op)
+    if isinstance(op, Sign):
+        result = op.signer.sign_message(op.message)
+        if inspect.isawaitable(result):
+            if hasattr(result, "close"):
+                result.close()
+            raise ProtocolError("sign_message returned an awaitable; use AsyncDominusNodeClient for async signers")
+        return result
+    if isinstance(op, Call):
+        return op.fn(*op.args)
+    raise TypeError(f"unknown op {op!r}")
+
+
+async def _exec_async(http: AsyncHttpClient, op: Op) -> Any:
+    if isinstance(op, Request):
+        return await http.request(op)
+    if isinstance(op, Sign):
+        result = op.signer.sign_message(op.message)
+        if inspect.isawaitable(result):
+            result = await result
+        return result
+    if isinstance(op, Call):
+        return await asyncio.to_thread(op.fn, *op.args)
+    raise TypeError(f"unknown op {op!r}")
+
+
+def drive_sync(http: SyncHttpClient, gen: Gen) -> Any:
+    value: Any = None
+    exc: Any = None
+    while True:
+        try:
+            op = gen.throw(exc) if exc is not None else gen.send(value)
+        except StopIteration as stop:
+            return stop.value
+        try:
+            value, exc = _exec_sync(http, op), None
+        except Exception as e:  # noqa: BLE001 - delivered into the generator
+            value, exc = None, e
+
+
+async def drive_async(http: AsyncHttpClient, gen: Gen) -> Any:
+    value: Any = None
+    exc: Any = None
+    while True:
+        try:
+            op = gen.throw(exc) if exc is not None else gen.send(value)
+        except StopIteration as stop:
+            return stop.value
+        try:
+            value, exc = await _exec_async(http, op), None
+        except Exception as e:  # noqa: BLE001
+            value, exc = None, e
+
+
+T = TypeVar("T")
+
+
+def _sync_method(fn: Callable[..., Gen]) -> Callable[..., Any]:
+    @functools.wraps(fn)
+    def wrapper(self: Any, *args: Any, **kwargs: Any) -> Any:
+        return drive_sync(self._http, fn(self, *args, **kwargs))
+
+    return wrapper
+
+
+def _async_method(fn: Callable[..., Gen]) -> Callable[..., Any]:
+    @functools.wraps(fn)
+    async def wrapper(self: Any, *args: Any, **kwargs: Any) -> Any:
+        return await drive_async(self._http, fn(self, *args, **kwargs))
+
+    return wrapper
+
+
+def make_variants(core: Type[T]) -> Tuple[Type[T], Type[T]]:
+    """Build (SyncResource, AsyncResource) subclasses: every public generator method becomes a plain/async method."""
+    name = core.__name__.lstrip("_")
+    sync_ns: Dict[str, Any] = {"__doc__": core.__doc__, "__module__": core.__module__}
+    async_ns: Dict[str, Any] = {"__doc__": core.__doc__, "__module__": core.__module__}
+    for attr, value in vars(core).items():
+        if not attr.startswith("_") and inspect.isgeneratorfunction(value):
+            sync_ns[attr] = _sync_method(value)
+            async_ns[attr] = _async_method(value)
+    return type(name, (core,), sync_ns), type("Async" + name, (core,), async_ns)  # type: ignore[return-value]

dominusnode/client.py

@@ -0,0 +1,192 @@
+"""DominusNode relay-network clients (sync and async, identical surface)."""
+
+from __future__ import annotations
+
+from typing import Any, Dict, Generator, Optional
+
+import httpx
+
+from ._ops import drive_async, drive_sync
+from .constants import DEFAULT_BASE_URL, DEFAULT_HTTP_PROXY_PORT, DEFAULT_PROXY_HOST, DEFAULT_SOCKS5_PROXY_PORT
+from .errors import DominusNodeError
+from .http_client import AsyncHttpClient, SyncHttpClient
+from .resources import (
+    AgenticWalletResource, AsyncAgenticWalletResource, AsyncAuthResource, AsyncCreditsResource,
+    AsyncKeysResource, AsyncNetworkResource, AsyncNodesResource, AsyncPayoutsResource,
+    AsyncPayoutWalletResource, AsyncProxyResource, AsyncSessionsResource, AsyncTeamsResource,
+    AsyncUsageResource, AsyncWalletAuthResource, AsyncWalletResource, AsyncX402Resource, AuthResource,
+    CreditsResource, KeysResource, NetworkResource, NodesResource, PayoutsResource, PayoutWalletResource,
+    ProxyResource, SessionsResource, TeamsResource, UsageResource, WalletAuthResource, WalletResource,
+    X402Resource, _AuthResource, _Ctx,
+)
+from .token_manager import AsyncTokenManager, TokenManager
+from .validation import validate_api_key
+
+
+def _connect_gen(ctx: _Ctx, auth: Any, api_key: str) -> Generator[Any, Any, Dict[str, Any]]:
+    validate_api_key(api_key)
+    try:
+        r = yield from _AuthResource.verify_key(auth, api_key)
+    except DominusNodeError as err:
+        if err.code == "MFA_REQUIRED":
+            ctx.api_key = api_key
+            return {"mfaRequired": True}
+        raise
+    ctx.api_key = api_key
+    ctx.tokens.set_tokens(r.get("token"), r.get("refreshToken"))
+    return {"mfaRequired": False, "userId": r.get("userId")}
+
+
+def _disconnect_gen(ctx: _Ctx, auth: Any) -> Generator[Any, Any, None]:
+    try:
+        if ctx.tokens.has_tokens():
+            try:
+                yield from _AuthResource.logout(auth)
+            except Exception:  # noqa: BLE001 - best effort
+                pass
+    finally:
+        ctx.api_key = None
+        ctx.tokens.clear()
+
+
+class _ClientBase:
+    _ctx: _Ctx
+
+    @property
+    def is_connected(self) -> bool:
+        """True when an API key or any JWT is held."""
+        return self._ctx.api_key is not None or self._ctx.tokens.has_tokens()
+
+    def __repr__(self) -> str:
+        return f"{type(self).__name__}(connected={'true' if self.is_connected else 'false'})"
+
+    __str__ = __repr__
+
+    def to_json(self) -> Dict[str, Any]:
+        return {"connected": self.is_connected}
+
+    def __reduce__(self) -> Any:
+        raise TypeError("client cannot be pickled")
+
+
+class DominusNodeClient(_ClientBase):
+    """Synchronous client::
+
+        with DominusNodeClient() as dn:
+            dn.connect_with_key(os.environ["DOMINUSNODE_API_KEY"])
+            res = dn.proxy.fetch("https://example.com", country="US")
+    """
+
+    def __init__(
+        self,
+        base_url: str = DEFAULT_BASE_URL,
+        proxy_host: str = DEFAULT_PROXY_HOST,
+        http_proxy_port: int = DEFAULT_HTTP_PROXY_PORT,
+        socks5_proxy_port: int = DEFAULT_SOCKS5_PROXY_PORT,
+        access_token: Optional[str] = None,
+        refresh_token: Optional[str] = None,
+        transport: Optional[httpx.BaseTransport] = None,
+        gateway_tls: Any = None,
+    ) -> None:
+        tokens = TokenManager()
+        self._ctx = ctx = _Ctx(tokens)
+        self._http = http = SyncHttpClient(base_url, tokens, lambda: ctx.api_key, transport)
+        self.auth = AuthResource(http, ctx)
+        self.wallet_auth = WalletAuthResource(http, ctx)
+        self.keys = KeysResource(http, ctx)
+        self.wallet = WalletResource(http, ctx)
+        self.agentic_wallets = AgenticWalletResource(http, ctx)
+        self.teams = TeamsResource(http, ctx)
+        self.usage = UsageResource(http, ctx)
+        self.sessions = SessionsResource(http, ctx)
+        self.x402 = X402Resource(http, ctx)
+        self.network = NetworkResource(http, ctx)
+        self.nodes = NodesResource(http, ctx)
+        self.credits = CreditsResource(http, ctx)
+        self.payout_wallet = PayoutWalletResource(http, ctx)
+        self.payouts = PayoutsResource(http, ctx)
+        self.proxy = ProxyResource(http, ctx, proxy_host, http_proxy_port, socks5_proxy_port, gateway_tls)
+
+        def refresh(rt: str) -> Any:
+            r = self.auth.refresh(rt)
+            return r.get("token"), r.get("refreshToken")
+
+        tokens.set_refresh_function(refresh)  # never cleared
+        if access_token:
+            tokens.set_tokens(access_token, refresh_token)
+
+    def connect_with_key(self, api_key: str) -> Dict[str, Any]:
+        """Returns {mfaRequired: False, userId} or {mfaRequired: True} (key-auth routes still work)."""
+        return drive_sync(self._http, _connect_gen(self._ctx, self.auth, api_key))
+
+    def disconnect(self) -> None:
+        """Best-effort logout, then clear the API key, access token and refresh token."""
+        drive_sync(self._http, _disconnect_gen(self._ctx, self.auth))
+
+    def close(self) -> None:
+        self.disconnect()
+        self._http.close()
+
+    def __enter__(self) -> "DominusNodeClient":
+        return self
+
+    def __exit__(self, *exc: object) -> None:
+        self.close()
+
+
+class AsyncDominusNodeClient(_ClientBase):
+    """asyncio client with the same surface; every resource method is a coroutine (signers may be async)."""
+
+    def __init__(
+        self,
+        base_url: str = DEFAULT_BASE_URL,
+        proxy_host: str = DEFAULT_PROXY_HOST,
+        http_proxy_port: int = DEFAULT_HTTP_PROXY_PORT,
+        socks5_proxy_port: int = DEFAULT_SOCKS5_PROXY_PORT,
+        access_token: Optional[str] = None,
+        refresh_token: Optional[str] = None,
+        transport: Optional[httpx.AsyncBaseTransport] = None,
+        gateway_tls: Any = None,
+    ) -> None:
+        tokens = AsyncTokenManager()
+        self._ctx = ctx = _Ctx(tokens)
+        self._http = http = AsyncHttpClient(base_url, tokens, lambda: ctx.api_key, transport)
+        self.auth = AsyncAuthResource(http, ctx)
+        self.wallet_auth = AsyncWalletAuthResource(http, ctx)
+        self.keys = AsyncKeysResource(http, ctx)
+        self.wallet = AsyncWalletResource(http, ctx)
+        self.agentic_wallets = AsyncAgenticWalletResource(http, ctx)
+        self.teams = AsyncTeamsResource(http, ctx)
+        self.usage = AsyncUsageResource(http, ctx)
+        self.sessions = AsyncSessionsResource(http, ctx)
+        self.x402 = AsyncX402Resource(http, ctx)
+        self.network = AsyncNetworkResource(http, ctx)
+        self.nodes = AsyncNodesResource(http, ctx)
+        self.credits = AsyncCreditsResource(http, ctx)
+        self.payout_wallet = AsyncPayoutWalletResource(http, ctx)
+        self.payouts = AsyncPayoutsResource(http, ctx)
+        self.proxy = AsyncProxyResource(http, ctx, proxy_host, http_proxy_port, socks5_proxy_port, gateway_tls)
+
+        async def refresh(rt: str) -> Any:
+            r = await self.auth.refresh(rt)
+            return r.get("token"), r.get("refreshToken")
+
+        tokens.set_refresh_function(refresh)
+        if access_token:
+            tokens.set_tokens(access_token, refresh_token)
+
+    async def connect_with_key(self, api_key: str) -> Dict[str, Any]:
+        return await drive_async(self._http, _connect_gen(self._ctx, self.auth, api_key))
+
+    async def disconnect(self) -> None:
+        await drive_async(self._http, _disconnect_gen(self._ctx, self.auth))
+
+    async def close(self) -> None:
+        await self.disconnect()
+        await self._http.close()
+
+    async def __aenter__(self) -> "AsyncDominusNodeClient":
+        return self
+
+    async def __aexit__(self, *exc: object) -> None:
+        await self.close()

dominusnode/constants.py

@@ -0,0 +1,24 @@
+"""SDK-wide constants (mirrors sdks/node/src/constants.ts)."""
+
+SDK_VERSION = "2.0.0"
+USER_AGENT = f"dominusnode-sdk-python/{SDK_VERSION}"
+DEFAULT_BASE_URL = "https://api.dominusnode.daedalusdevelopmentgroup.com"
+DEFAULT_PROXY_HOST = "proxy.dominusnode.daedalusdevelopmentgroup.com"
+DEFAULT_HTTP_PROXY_PORT = 8080
+DEFAULT_SOCKS5_PROXY_PORT = 1080
+#: Gateway HTTPS proxy listener (PROXY_TLS_PORT), used with gateway_tls.
+DEFAULT_TLS_PROXY_PORT = 8443
+#: Refresh JWTs this many seconds before expiry.
+TOKEN_REFRESH_BUFFER_SECONDS = 60
+#: Hard cap on any response body the SDK reads (API or proxy fetch).
+MAX_RESPONSE_BYTES = 10 * 1024 * 1024
+#: API request timeout (seconds).
+REQUEST_TIMEOUT_SECONDS = 30.0
+#: 429 retry: one retry, wait = min(Retry-After, 10s) +/-10% jitter, floor 100ms.
+MAX_RATE_LIMIT_RETRIES = 1
+MAX_RETRY_WAIT_SECONDS = 10.0
+MIN_RETRY_WAIT_SECONDS = 0.1
+#: Largest value accepted for any *_cents argument (PostgreSQL INTEGER max).
+MAX_AMOUNT_CENTS = 2_147_483_647
+#: 1 USD = 1,000,000 µUSD.
+MUSD_PER_USD = 1_000_000

dominusnode/errors.py

@@ -0,0 +1,153 @@
+"""Error hierarchy.
+
+Every message passes through :func:`scrub_credentials` so API keys
+(dn_live_/dn_test_/dn_node_/dn_proxy_) and JWTs never reach logs or callers
+via error strings.
+"""
+
+from __future__ import annotations
+
+import re
+from typing import Dict, Optional, Union
+
+_CREDENTIAL_PATTERNS = [
+    re.compile(r"dn_(?:live|test|node|proxy)_[A-Za-z0-9_-]+"),
+    re.compile(r"eyJ[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\.[A-Za-z0-9_-]*"),
+]
+
+Details = Dict[str, Union[int, float, str]]
+
+
+def scrub_credentials(message: object) -> str:
+    out = str(message)
+    for pattern in _CREDENTIAL_PATTERNS:
+        out = pattern.sub("[REDACTED]", out)
+    return out
+
+
+class DominusNodeError(Exception):
+    """Base class. ``code`` is the server's error code (e.g. ``INVALID_CHALLENGE``)."""
+
+    default_message = "DominusNode error"
+
+    def __init__(
+        self,
+        message: Optional[str] = None,
+        status_code: Optional[int] = None,
+        code: Optional[str] = None,
+        details: Optional[Details] = None,
+    ) -> None:
+        self.message = scrub_credentials(message if message is not None else self.default_message)
+        self.status_code = status_code
+        self.code = code
+        self.details = details
+        super().__init__(self.message)
+
+    def __str__(self) -> str:
+        return self.message
+
+    def __repr__(self) -> str:
+        return f"{type(self).__name__}({self.message!r}, status_code={self.status_code!r}, code={self.code!r})"
+
+
+class AuthenticationError(DominusNodeError):
+    default_message = "Authentication failed"
+
+    def __init__(self, message: Optional[str] = None, code: Optional[str] = None, details: Optional[Details] = None) -> None:
+        super().__init__(message, 401, code, details)
+
+
+class InsufficientBalanceError(DominusNodeError):
+    default_message = "Insufficient balance"
+
+    def __init__(self, message: Optional[str] = None, code: Optional[str] = None, details: Optional[Details] = None) -> None:
+        super().__init__(message, 402, code, details)
+
+
+class AuthorizationError(DominusNodeError):
+    default_message = "Access denied"
+
+    def __init__(self, message: Optional[str] = None, code: Optional[str] = None, details: Optional[Details] = None) -> None:
+        super().__init__(message, 403, code, details)
+
+
+class NotFoundError(DominusNodeError):
+    default_message = "Resource not found"
+
+    def __init__(self, message: Optional[str] = None, code: Optional[str] = None, details: Optional[Details] = None) -> None:
+        super().__init__(message, 404, code, details)
+
+
+class ConflictError(DominusNodeError):
+    default_message = "Resource conflict"
+
+    def __init__(self, message: Optional[str] = None, code: Optional[str] = None, details: Optional[Details] = None) -> None:
+        super().__init__(message, 409, code, details)
+
+
+class RateLimitError(DominusNodeError):
+    default_message = "Rate limit exceeded"
+
+    def __init__(
+        self,
+        message: Optional[str] = None,
+        retry_after_seconds: int = 60,
+        code: Optional[str] = None,
+        details: Optional[Details] = None,
+    ) -> None:
+        super().__init__(message, 429, code, details)
+        self.retry_after_seconds = retry_after_seconds
+
+
+class ServerError(DominusNodeError):
+    default_message = "Server error"
+
+    def __init__(
+        self,
+        message: Optional[str] = None,
+        status_code: int = 500,
+        code: Optional[str] = None,
+        details: Optional[Details] = None,
+    ) -> None:
+        super().__init__(message, status_code, code, details)
+
+
+class ValidationError(DominusNodeError):
+    """HTTP 400, or a client-side argument check (status_code None, code INVALID_ARGUMENT)."""
+
+    default_message = "Validation failed"
+
+    def __init__(
+        self,
+        message: Optional[str] = None,
+        status_code: Optional[int] = 400,
+        code: Optional[str] = None,
+        details: Optional[Details] = None,
+    ) -> None:
+        super().__init__(message, status_code, code, details)
+
+
+class NetworkError(DominusNodeError):
+    default_message = "Network error"
+
+    def __init__(self, message: Optional[str] = None) -> None:
+        super().__init__(message)
+
+
+class ProtocolError(DominusNodeError):
+    """The server sent something the SDK refuses to act on, or a signer failed."""
+
+    def __init__(self, message: str) -> None:
+        super().__init__(message)
+
+
+class ProxyError(DominusNodeError):
+    """Failure inside proxy.fetch(): blocked target, refused tunnel, timeout."""
+
+    def __init__(self, message: str, status_code: Optional[int] = None) -> None:
+        super().__init__(message, status_code)
+
+
+def invalid_arg(message: str) -> ValidationError:
+    """Client-side argument validation failure (no request sent)."""
+    return ValidationError(message, None, "INVALID_ARGUMENT")