dominusnode 1.0.0__py3-none-any.whl

dominusnode/__init__.py

@@ -0,0 +1,151 @@
+"""Dominus Node Python SDK.
+
+Official Python SDK for the Dominus Node rotating proxy-as-a-service platform.
+
+Provides both synchronous and asynchronous clients::
+
+    # Sync
+    from dominusnode import DominusNodeClient
+
+    with DominusNodeClient(base_url="http://localhost:3000") as client:
+        client.connect_with_credentials("user@example.com", "s3cret!Pass")
+        print(client.wallet.get_balance())
+
+    # Async
+    from dominusnode import AsyncDominusNodeClient
+
+    async with AsyncDominusNodeClient(base_url="http://localhost:3000") as client:
+        await client.connect_with_credentials("user@example.com", "s3cret!Pass")
+        print(await client.wallet.get_balance())
+"""
+
+from .client import AsyncDominusNodeClient, DominusNodeClient
+from .constants import SDK_VERSION
+from .errors import (
+    AuthenticationError,
+    AuthorizationError,
+    ConflictError,
+    DominusNodeError,
+    InsufficientBalanceError,
+    NetworkError,
+    NotFoundError,
+    ProxyError,
+    RateLimitError,
+    ServerError,
+    ValidationError,
+)
+from .x402 import X402Info, X402Facilitator, X402Pricing
+from .wallet_auth import WalletChallenge, WalletVerifyResult, WalletLinkResult
+from .types import (
+    ActiveSession,
+    AdminUser,
+    AdminUserDetail,
+    AdminUsersResponse,
+    ApiKey,
+    CreatedApiKey,
+    CryptoInvoice,
+    DailyRevenue,
+    DailyUsage,
+    GeoTargeting,
+    LoginResult,
+    MfaSetup,
+    MfaStatus,
+    Pagination,
+    Plan,
+    ProxyConfig,
+    ProxyEndpointConfig,
+    ProxyEndpoints,
+    ProxyHealth,
+    ProxyStatus,
+    ProxyUrlOptions,
+    ProviderStat,
+    RevenueStats,
+    StripeCheckout,
+    SlotsInfo,
+    SystemStats,
+    TopHost,
+    UsagePagination,
+    UsagePeriod,
+    UsageRecord,
+    UsageResponse,
+    UsageSummary,
+    User,
+    UserPlanInfo,
+    UserPlanUsage,
+    Wallet,
+    WaitlistCount,
+    WaitlistJoinResult,
+    WalletForecast,
+    WalletTransaction,
+)
+
+__version__ = SDK_VERSION
+
+__all__ = [
+    # Clients
+    "DominusNodeClient",
+    "AsyncDominusNodeClient",
+    # Errors
+    "DominusNodeError",
+    "AuthenticationError",
+    "AuthorizationError",
+    "RateLimitError",
+    "InsufficientBalanceError",
+    "ValidationError",
+    "NotFoundError",
+    "ConflictError",
+    "ServerError",
+    "NetworkError",
+    "ProxyError",
+    # Types
+    "User",
+    "LoginResult",
+    "MfaStatus",
+    "MfaSetup",
+    "ApiKey",
+    "CreatedApiKey",
+    "Wallet",
+    "WalletTransaction",
+    "WalletForecast",
+    "StripeCheckout",
+    "CryptoInvoice",
+    "UsageSummary",
+    "UsageRecord",
+    "UsagePagination",
+    "UsagePeriod",
+    "UsageResponse",
+    "DailyUsage",
+    "TopHost",
+    "Plan",
+    "UserPlanUsage",
+    "UserPlanInfo",
+    "ActiveSession",
+    "ProxyUrlOptions",
+    "ProxyHealth",
+    "ProviderStat",
+    "ProxyEndpoints",
+    "ProxyStatus",
+    "GeoTargeting",
+    "ProxyEndpointConfig",
+    "ProxyConfig",
+    "AdminUser",
+    "AdminUserDetail",
+    "Pagination",
+    "AdminUsersResponse",
+    "RevenueStats",
+    "DailyRevenue",
+    "SlotsInfo",
+    "WaitlistJoinResult",
+    "WaitlistCount",
+    "SystemStats",
+    # x402
+    "X402Info",
+    "X402Facilitator",
+    "X402Pricing",
+    # Wallet Auth
+    "WalletChallenge",
+    "WalletVerifyResult",
+    "WalletLinkResult",
+    # Constants
+    "SDK_VERSION",
+]

dominusnode/admin.py

@@ -0,0 +1,252 @@
+"""Admin resource -- user management, revenue analytics, and system stats.
+
+All admin endpoints require the authenticated user to have admin privileges.
+"""
+
+from __future__ import annotations
+
+from typing import List, Optional
+from urllib.parse import quote
+
+from .http_client import AsyncHttpClient, SyncHttpClient
+from .types import (
+    AdminUser,
+    AdminUserDetail,
+    AdminUsersResponse,
+    DailyRevenue,
+    Pagination,
+    RevenueStats,
+    SystemStats,
+    UsagePeriod,
+)
+
+
+def _parse_admin_user(u: dict) -> AdminUser:
+    return AdminUser(
+        id=u["id"],
+        email=u["email"],
+        status=u["status"],
+        plan_id=u.get("planId", "payg"),
+        balance_cents=u.get("balanceCents", 0),
+        created_at=str(u.get("createdAt", "")),
+        is_admin=u.get("isAdmin", False),
+    )
+
+
+def _parse_admin_user_detail(u: dict) -> AdminUserDetail:
+    return AdminUserDetail(
+        id=u["id"],
+        email=u["email"],
+        status=u["status"],
+        plan_id=u.get("planId", "payg"),
+        balance_cents=u.get("balanceCents", 0),
+        created_at=str(u.get("createdAt", "")),
+        is_admin=u.get("isAdmin", False),
+        api_key_count=u.get("apiKeyCount", 0),
+        total_usage_bytes=u.get("totalUsageBytes", 0),
+        total_spent_cents=u.get("totalSpentCents", 0),
+        last_active=str(u["lastActive"]) if u.get("lastActive") else None,
+    )
+
+
+def _build_date_params(since: Optional[str], until: Optional[str]) -> dict:
+    params: dict = {}
+    if since:
+        params["since"] = since
+    if until:
+        params["until"] = until
+    return params
+
+
+# ──────────────────────────────────────────────────────────────────────
+# Sync
+# ──────────────────────────────────────────────────────────────────────
+
+
+class AdminResource:
+    """Synchronous admin operations."""
+
+    def __init__(self, http: SyncHttpClient) -> None:
+        self._http = http
+
+    # ── User Management ──────────────────────────────────────────────
+
+    def list_users(self, *, page: int = 1, limit: int = 20) -> AdminUsersResponse:
+        """List all users (paginated)."""
+        data = self._http.get("/api/admin/users", params={"page": page, "limit": limit})
+        users = [_parse_admin_user(u) for u in data.get("users", [])]
+        p = data.get("pagination", {})
+        pagination = Pagination(
+            page=p.get("page", page),
+            limit=p.get("limit", limit),
+            total=p.get("total", 0),
+            total_pages=p.get("totalPages", 0),
+        )
+        return AdminUsersResponse(users=users, pagination=pagination)
+
+    def get_user(self, user_id: str) -> AdminUserDetail:
+        """Get detailed information about a specific user."""
+        data = self._http.get(f"/api/admin/users/{quote(user_id, safe='')}")
+        return _parse_admin_user_detail(data["user"])
+
+    def suspend_user(self, user_id: str) -> None:
+        """Suspend a user account."""
+        self._http.put(f"/api/admin/users/{quote(user_id, safe='')}/suspend")
+
+    def activate_user(self, user_id: str) -> None:
+        """Reactivate a suspended user account."""
+        self._http.put(f"/api/admin/users/{quote(user_id, safe='')}/activate")
+
+    def delete_user(self, user_id: str) -> None:
+        """Soft-delete a user account."""
+        self._http.delete(f"/api/admin/users/{quote(user_id, safe='')}")
+
+    # ── Revenue Analytics ────────────────────────────────────────────
+
+    def get_revenue(
+        self,
+        *,
+        since: Optional[str] = None,
+        until: Optional[str] = None,
+    ) -> RevenueStats:
+        """Get revenue statistics for the given period."""
+        params = _build_date_params(since, until)
+        data = self._http.get("/api/admin/revenue", params=params)
+        period_data = data.get("period", {})
+        return RevenueStats(
+            total_revenue_cents=data.get("totalRevenueCents", 0),
+            total_revenue_usd=data.get("totalRevenueUsd", 0),
+            total_transactions=data.get("totalTransactions", 0),
+            avg_transaction_cents=data.get("avgTransactionCents", 0),
+            avg_transaction_usd=data.get("avgTransactionUsd", 0),
+            top_up_count=data.get("topUpCount", 0),
+            unique_paying_users=data.get("uniquePayingUsers", 0),
+            period=UsagePeriod(
+                since=period_data.get("since", ""),
+                until=period_data.get("until", ""),
+            ),
+        )
+
+    def get_daily_revenue(
+        self,
+        *,
+        since: Optional[str] = None,
+        until: Optional[str] = None,
+    ) -> List[DailyRevenue]:
+        """Get daily revenue breakdown."""
+        params = _build_date_params(since, until)
+        data = self._http.get("/api/admin/revenue/daily", params=params)
+        return [
+            DailyRevenue(
+                date=d["date"],
+                revenue_cents=d.get("revenueCents", 0),
+                revenue_usd=d.get("revenueUsd", 0),
+                transaction_count=d.get("transactionCount", 0),
+            )
+            for d in data.get("days", [])
+        ]
+
+    # ── System Stats ─────────────────────────────────────────────────
+
+    def get_stats(self) -> SystemStats:
+        """Get system-wide statistics."""
+        data = self._http.get("/api/admin/stats")
+        return SystemStats(
+            total_users=data.get("totalUsers", 0),
+            active_users=data.get("activeUsers", 0),
+            suspended_users=data.get("suspendedUsers", 0),
+            total_api_keys=data.get("totalApiKeys", 0),
+            active_api_keys=data.get("activeApiKeys", 0),
+            total_sessions=data.get("totalSessions", 0),
+            active_sessions=data.get("activeSessions", 0),
+        )
+
+
+# ──────────────────────────────────────────────────────────────────────
+# Async
+# ──────────────────────────────────────────────────────────────────────
+
+
+class AsyncAdminResource:
+    """Asynchronous admin operations."""
+
+    def __init__(self, http: AsyncHttpClient) -> None:
+        self._http = http
+
+    async def list_users(self, *, page: int = 1, limit: int = 20) -> AdminUsersResponse:
+        data = await self._http.get("/api/admin/users", params={"page": page, "limit": limit})
+        users = [_parse_admin_user(u) for u in data.get("users", [])]
+        p = data.get("pagination", {})
+        pagination = Pagination(
+            page=p.get("page", page),
+            limit=p.get("limit", limit),
+            total=p.get("total", 0),
+            total_pages=p.get("totalPages", 0),
+        )
+        return AdminUsersResponse(users=users, pagination=pagination)
+
+    async def get_user(self, user_id: str) -> AdminUserDetail:
+        data = await self._http.get(f"/api/admin/users/{quote(user_id, safe='')}")
+        return _parse_admin_user_detail(data["user"])
+
+    async def suspend_user(self, user_id: str) -> None:
+        await self._http.put(f"/api/admin/users/{quote(user_id, safe='')}/suspend")
+
+    async def activate_user(self, user_id: str) -> None:
+        await self._http.put(f"/api/admin/users/{quote(user_id, safe='')}/activate")
+
+    async def delete_user(self, user_id: str) -> None:
+        await self._http.delete(f"/api/admin/users/{quote(user_id, safe='')}")
+
+    async def get_revenue(
+        self,
+        *,
+        since: Optional[str] = None,
+        until: Optional[str] = None,
+    ) -> RevenueStats:
+        params = _build_date_params(since, until)
+        data = await self._http.get("/api/admin/revenue", params=params)
+        period_data = data.get("period", {})
+        return RevenueStats(
+            total_revenue_cents=data.get("totalRevenueCents", 0),
+            total_revenue_usd=data.get("totalRevenueUsd", 0),
+            total_transactions=data.get("totalTransactions", 0),
+            avg_transaction_cents=data.get("avgTransactionCents", 0),
+            avg_transaction_usd=data.get("avgTransactionUsd", 0),
+            top_up_count=data.get("topUpCount", 0),
+            unique_paying_users=data.get("uniquePayingUsers", 0),
+            period=UsagePeriod(
+                since=period_data.get("since", ""),
+                until=period_data.get("until", ""),
+            ),
+        )
+
+    async def get_daily_revenue(
+        self,
+        *,
+        since: Optional[str] = None,
+        until: Optional[str] = None,
+    ) -> List[DailyRevenue]:
+        params = _build_date_params(since, until)
+        data = await self._http.get("/api/admin/revenue/daily", params=params)
+        return [
+            DailyRevenue(
+                date=d["date"],
+                revenue_cents=d.get("revenueCents", 0),
+                revenue_usd=d.get("revenueUsd", 0),
+                transaction_count=d.get("transactionCount", 0),
+            )
+            for d in data.get("days", [])
+        ]
+
+    async def get_stats(self) -> SystemStats:
+        data = await self._http.get("/api/admin/stats")
+        return SystemStats(
+            total_users=data.get("totalUsers", 0),
+            active_users=data.get("activeUsers", 0),
+            suspended_users=data.get("suspendedUsers", 0),
+            total_api_keys=data.get("totalApiKeys", 0),
+            active_api_keys=data.get("activeApiKeys", 0),
+            total_sessions=data.get("totalSessions", 0),
+            active_sessions=data.get("activeSessions", 0),
+        )

dominusnode/agent_wallet.py

@@ -0,0 +1,240 @@
+"""Agentic wallet resource -- server-side custodial sub-wallets with spending limits."""
+
+from __future__ import annotations
+
+from typing import List, Optional
+from urllib.parse import quote
+
+from .http_client import AsyncHttpClient, SyncHttpClient
+from .types import AgenticWallet, AgenticWalletTransaction
+from .wallet import _validate_amount_cents
+
+
+def _parse_agentic_wallet(data: dict) -> AgenticWallet:
+    """Parse an agentic wallet response dict into an AgenticWallet dataclass."""
+    return AgenticWallet(
+        id=data["id"],
+        label=data["label"],
+        balance_cents=data["balanceCents"],
+        spending_limit_cents=data["spendingLimitCents"],
+        status=data["status"],
+        created_at=data.get("createdAt", ""),
+        daily_limit_cents=data.get("dailyLimitCents"),
+        allowed_domains=data.get("allowedDomains"),
+    )
+
+
+class AgenticWalletResource:
+    """Synchronous agentic wallet operations."""
+
+    def __init__(self, http: SyncHttpClient) -> None:
+        self._http = http
+
+    def create(
+        self,
+        label: str,
+        spending_limit_cents: int = 10000,
+        daily_limit_cents: Optional[int] = None,
+        allowed_domains: Optional[List[str]] = None,
+    ) -> AgenticWallet:
+        """Create a new agentic wallet."""
+        _validate_amount_cents(spending_limit_cents, "spending_limit_cents")
+        body: dict = {
+            "label": label,
+            "spendingLimitCents": spending_limit_cents,
+        }
+        if daily_limit_cents is not None:
+            _validate_amount_cents(daily_limit_cents, "daily_limit_cents")
+            body["dailyLimitCents"] = daily_limit_cents
+        if allowed_domains is not None:
+            body["allowedDomains"] = allowed_domains
+        data = self._http.post("/api/agent-wallet", json=body)
+        return _parse_agentic_wallet(data)
+
+    def list(self) -> List[AgenticWallet]:
+        """List all agentic wallets."""
+        data = self._http.get("/api/agent-wallet")
+        return [_parse_agentic_wallet(w) for w in data["wallets"]]
+
+    def get(self, wallet_id: str) -> AgenticWallet:
+        """Get a single agentic wallet."""
+        data = self._http.get(f"/api/agent-wallet/{quote(wallet_id, safe='')}")
+        return _parse_agentic_wallet(data)
+
+    def fund(self, wallet_id: str, amount_cents: int) -> AgenticWalletTransaction:
+        """Fund an agentic wallet from the main wallet."""
+        _validate_amount_cents(amount_cents, "amount_cents")
+        data = self._http.post(f"/api/agent-wallet/{quote(wallet_id, safe='')}/fund", json={
+            "amountCents": amount_cents,
+        })
+        tx = data["transaction"]
+        return AgenticWalletTransaction(
+            id=tx["id"],
+            wallet_id=tx["walletId"],
+            type=tx["type"],
+            amount_cents=tx["amountCents"],
+            description=tx["description"],
+            session_id=tx.get("sessionId"),
+            created_at=tx["createdAt"],
+        )
+
+    def transactions(
+        self, wallet_id: str, limit: int = 50, offset: int = 0
+    ) -> List[AgenticWalletTransaction]:
+        """Get transaction history for an agentic wallet."""
+        data = self._http.get(
+            f"/api/agent-wallet/{quote(wallet_id, safe='')}/transactions?limit={limit}&offset={offset}"
+        )
+        return [
+            AgenticWalletTransaction(
+                id=tx["id"],
+                wallet_id=tx["walletId"],
+                type=tx["type"],
+                amount_cents=tx["amountCents"],
+                description=tx["description"],
+                session_id=tx.get("sessionId"),
+                created_at=tx["createdAt"],
+            )
+            for tx in data["transactions"]
+        ]
+
+    def freeze(self, wallet_id: str) -> AgenticWallet:
+        """Freeze an agentic wallet."""
+        data = self._http.post(f"/api/agent-wallet/{quote(wallet_id, safe='')}/freeze", json={})
+        return _parse_agentic_wallet(data)
+
+    def unfreeze(self, wallet_id: str) -> AgenticWallet:
+        """Unfreeze an agentic wallet."""
+        data = self._http.post(f"/api/agent-wallet/{quote(wallet_id, safe='')}/unfreeze", json={})
+        return _parse_agentic_wallet(data)
+
+    def delete(self, wallet_id: str) -> int:
+        """Delete an agentic wallet and refund remaining balance. Returns refunded cents."""
+        data = self._http.delete(f"/api/agent-wallet/{quote(wallet_id, safe='')}")
+        return data["refundedCents"]
+
+    def update_wallet_policy(
+        self,
+        wallet_id: str,
+        daily_limit_cents: Optional[int] = None,
+        allowed_domains: Optional[List[str]] = None,
+    ) -> AgenticWallet:
+        """Update the policy on an agentic wallet."""
+        body: dict = {}
+        if daily_limit_cents is not None:
+            _validate_amount_cents(daily_limit_cents, "daily_limit_cents")
+            body["dailyLimitCents"] = daily_limit_cents
+        if allowed_domains is not None:
+            body["allowedDomains"] = allowed_domains
+        data = self._http.patch(
+            f"/api/agent-wallet/{quote(wallet_id, safe='')}/policy", json=body
+        )
+        return _parse_agentic_wallet(data)
+
+
+class AsyncAgenticWalletResource:
+    """Asynchronous agentic wallet operations."""
+
+    def __init__(self, http: AsyncHttpClient) -> None:
+        self._http = http
+
+    async def create(
+        self,
+        label: str,
+        spending_limit_cents: int = 10000,
+        daily_limit_cents: Optional[int] = None,
+        allowed_domains: Optional[List[str]] = None,
+    ) -> AgenticWallet:
+        """Create a new agentic wallet."""
+        _validate_amount_cents(spending_limit_cents, "spending_limit_cents")
+        body: dict = {
+            "label": label,
+            "spendingLimitCents": spending_limit_cents,
+        }
+        if daily_limit_cents is not None:
+            _validate_amount_cents(daily_limit_cents, "daily_limit_cents")
+            body["dailyLimitCents"] = daily_limit_cents
+        if allowed_domains is not None:
+            body["allowedDomains"] = allowed_domains
+        data = await self._http.post("/api/agent-wallet", json=body)
+        return _parse_agentic_wallet(data)
+
+    async def list(self) -> List[AgenticWallet]:
+        """List all agentic wallets."""
+        data = await self._http.get("/api/agent-wallet")
+        return [_parse_agentic_wallet(w) for w in data["wallets"]]
+
+    async def get(self, wallet_id: str) -> AgenticWallet:
+        """Get a single agentic wallet."""
+        data = await self._http.get(f"/api/agent-wallet/{quote(wallet_id, safe='')}")
+        return _parse_agentic_wallet(data)
+
+    async def fund(self, wallet_id: str, amount_cents: int) -> AgenticWalletTransaction:
+        """Fund an agentic wallet from the main wallet."""
+        _validate_amount_cents(amount_cents, "amount_cents")
+        data = await self._http.post(f"/api/agent-wallet/{quote(wallet_id, safe='')}/fund", json={
+            "amountCents": amount_cents,
+        })
+        tx = data["transaction"]
+        return AgenticWalletTransaction(
+            id=tx["id"],
+            wallet_id=tx["walletId"],
+            type=tx["type"],
+            amount_cents=tx["amountCents"],
+            description=tx["description"],
+            session_id=tx.get("sessionId"),
+            created_at=tx["createdAt"],
+        )
+
+    async def transactions(
+        self, wallet_id: str, limit: int = 50, offset: int = 0
+    ) -> List[AgenticWalletTransaction]:
+        """Get transaction history for an agentic wallet."""
+        data = await self._http.get(
+            f"/api/agent-wallet/{quote(wallet_id, safe='')}/transactions?limit={limit}&offset={offset}"
+        )
+        return [
+            AgenticWalletTransaction(
+                id=tx["id"],
+                wallet_id=tx["walletId"],
+                type=tx["type"],
+                amount_cents=tx["amountCents"],
+                description=tx["description"],
+                session_id=tx.get("sessionId"),
+                created_at=tx["createdAt"],
+            )
+            for tx in data["transactions"]
+        ]
+
+    async def freeze(self, wallet_id: str) -> AgenticWallet:
+        """Freeze an agentic wallet."""
+        data = await self._http.post(f"/api/agent-wallet/{quote(wallet_id, safe='')}/freeze", json={})
+        return _parse_agentic_wallet(data)
+
+    async def unfreeze(self, wallet_id: str) -> AgenticWallet:
+        """Unfreeze an agentic wallet."""
+        data = await self._http.post(f"/api/agent-wallet/{quote(wallet_id, safe='')}/unfreeze", json={})
+        return _parse_agentic_wallet(data)
+
+    async def delete(self, wallet_id: str) -> int:
+        """Delete an agentic wallet and refund remaining balance. Returns refunded cents."""
+        data = await self._http.delete(f"/api/agent-wallet/{quote(wallet_id, safe='')}")
+        return data["refundedCents"]
+
+    async def update_wallet_policy(
+        self,
+        wallet_id: str,
+        daily_limit_cents: Optional[int] = None,
+        allowed_domains: Optional[List[str]] = None,
+    ) -> AgenticWallet:
+        """Update the policy on an agentic wallet."""
+        body: dict = {}
+        if daily_limit_cents is not None:
+            _validate_amount_cents(daily_limit_cents, "daily_limit_cents")
+            body["dailyLimitCents"] = daily_limit_cents
+        if allowed_domains is not None:
+            body["allowedDomains"] = allowed_domains
+        data = await self._http.patch(
+            f"/api/agent-wallet/{quote(wallet_id, safe='')}/policy", json=body
+        )
+        return _parse_agentic_wallet(data)