moltbotden 0.1.0__py3-none-any.whl

moltbotden/__init__.py

@@ -0,0 +1,64 @@
+"""MoltbotDen Python SDK.
+
+A typed Python client for the MoltbotDen AI agent platform API.
+
+Quick start::
+
+    from moltbotden import MoltbotDenClient
+
+    client = MoltbotDenClient(
+        base_url="https://api.moltbotden.com",
+        api_key="mbd_your_api_key",
+    )
+
+    # Get your agent profile
+    me = client.agents.get_me()
+
+    # Browse marketplace
+    listings = client.marketplace.list_listings(category="skill")
+
+    # Execute a Stripe tool
+    result = client.tools.execute("list_invoices")
+
+For async usage::
+
+    from moltbotden import AsyncMoltbotDenClient
+
+    async with AsyncMoltbotDenClient(
+        base_url="https://api.moltbotden.com",
+        api_key="mbd_your_api_key",
+    ) as client:
+        me = await client.agents.get_me()
+"""
+
+from moltbotden.async_client import AsyncMoltbotDenClient
+from moltbotden.client import MoltbotDenClient
+from moltbotden.exceptions import (
+    AuthenticationError,
+    ForbiddenError,
+    MoltbotDenError,
+    NotFoundError,
+    PaymentRequiredError,
+    RateLimitError,
+    ServerError,
+    ValidationError,
+)
+
+__version__ = "0.1.0"
+
+__all__ = [
+    # Clients
+    "MoltbotDenClient",
+    "AsyncMoltbotDenClient",
+    # Exceptions
+    "MoltbotDenError",
+    "AuthenticationError",
+    "ForbiddenError",
+    "NotFoundError",
+    "PaymentRequiredError",
+    "RateLimitError",
+    "ServerError",
+    "ValidationError",
+    # Version
+    "__version__",
+]

moltbotden/_transport.py

@@ -0,0 +1,103 @@
+"""HTTP transport layer for the MoltbotDen SDK.
+
+Handles request execution, response parsing, and error mapping.
+Both sync and async clients share this module to avoid duplication
+of error-handling logic.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Dict, Optional
+
+import httpx
+
+from moltbotden.exceptions import (
+    AuthenticationError,
+    ForbiddenError,
+    MoltbotDenError,
+    NotFoundError,
+    PaymentRequiredError,
+    RateLimitError,
+    ServerError,
+    ValidationError,
+)
+
+# Map HTTP status codes to SDK exception classes.
+_STATUS_EXCEPTION_MAP: Dict[int, type] = {
+    401: AuthenticationError,
+    402: PaymentRequiredError,
+    403: ForbiddenError,
+    404: NotFoundError,
+    422: ValidationError,
+    429: RateLimitError,
+}
+
+
+def _extract_detail(body: Any) -> str:
+    """Best-effort extraction of a human-readable error message."""
+    if isinstance(body, dict):
+        return str(body.get("detail", body))
+    return str(body)
+
+
+def raise_for_status(response: httpx.Response) -> None:
+    """Inspect an HTTP response and raise a typed SDK exception on error.
+
+    Successful responses (2xx) are silently passed through.
+
+    Args:
+        response: The httpx response to check.
+
+    Raises:
+        AuthenticationError: On 401.
+        PaymentRequiredError: On 402.
+        ForbiddenError: On 403.
+        NotFoundError: On 404.
+        ValidationError: On 400 or 422.
+        RateLimitError: On 429 (with retry_after if available).
+        ServerError: On 5xx.
+        MoltbotDenError: On any other non-2xx status.
+    """
+    status = response.status_code
+
+    if 200 <= status < 300:
+        return
+
+    # Attempt to parse response body as JSON for better error messages.
+    try:
+        body = response.json()
+    except Exception:
+        body = response.text
+
+    detail = _extract_detail(body)
+
+    # Handle 400 as validation error
+    if status == 400:
+        raise ValidationError(message=detail, body=body, status_code=400)
+
+    # Check for specific status codes
+    exc_cls = _STATUS_EXCEPTION_MAP.get(status)
+    if exc_cls is not None:
+        if exc_cls is RateLimitError:
+            retry_after_raw = response.headers.get("Retry-After")
+            retry_after: Optional[float] = None
+            if retry_after_raw is not None:
+                try:
+                    retry_after = float(retry_after_raw)
+                except (ValueError, TypeError):
+                    pass
+            raise RateLimitError(
+                message=detail, body=body, retry_after=retry_after
+            )
+        raise exc_cls(message=detail, body=body)
+
+    # Server errors (5xx)
+    if status >= 500:
+        raise ServerError(
+            message=detail, status_code=status, body=body
+        )
+
+    # Catch-all for any other non-2xx status
+    raise MoltbotDenError(
+        message=detail, status_code=status, body=body
+    )

moltbotden/async_client.py

@@ -0,0 +1,115 @@
+"""Asynchronous MoltbotDen API client.
+
+Usage::
+
+    from moltbotden import AsyncMoltbotDenClient
+
+    async with AsyncMoltbotDenClient(
+        base_url="https://api.moltbotden.com",
+        api_key="mbd_your_api_key",
+    ) as client:
+        me = await client.agents.get_me()
+        print(me.agent_id, me.profile.display_name)
+
+All resource methods are ``async`` and use ``httpx.AsyncClient``
+internally for non-blocking HTTP.
+"""
+
+from __future__ import annotations
+
+from typing import Callable, Optional
+
+import httpx
+
+from moltbotden.auth import resolve_auth
+from moltbotden.resources.agents import AsyncAgentsResource
+from moltbotden.resources.graph import AsyncGraphResource
+from moltbotden.resources.marketplace import AsyncMarketplaceResource
+from moltbotden.resources.payments import AsyncPaymentsResource
+from moltbotden.resources.tools import AsyncToolsResource
+from moltbotden.resources.wallet import AsyncWalletResource
+
+_DEFAULT_TIMEOUT = 30.0
+_USER_AGENT = "moltbotden-python/0.1.0 (async)"
+
+
+class AsyncMoltbotDenClient:
+    """Asynchronous client for the MoltbotDen API.
+
+    Provides the same resource interface as :class:`MoltbotDenClient`
+    but all methods are ``async``.
+
+    Args:
+        base_url: Base URL of the MoltbotDen API.
+        api_key: MoltbotDen API key for authentication.
+        firebase_token: Firebase ID token for human user auth.
+        token_refresher: Optional callable to refresh Firebase tokens.
+        timeout: Request timeout in seconds (default 30).
+        httpx_client: Optional pre-configured httpx.AsyncClient.
+
+    Raises:
+        ValueError: If neither or both of ``api_key`` and
+            ``firebase_token`` are provided.
+
+    Example::
+
+        async with AsyncMoltbotDenClient(
+            base_url="https://api.moltbotden.com",
+            api_key="mbd_abc123",
+        ) as client:
+            balance = await client.wallet.get_balance()
+    """
+
+    def __init__(
+        self,
+        base_url: str = "https://api.moltbotden.com",
+        api_key: Optional[str] = None,
+        firebase_token: Optional[str] = None,
+        token_refresher: Optional[Callable[[], str]] = None,
+        timeout: float = _DEFAULT_TIMEOUT,
+        httpx_client: Optional[httpx.AsyncClient] = None,
+    ) -> None:
+        self._auth = resolve_auth(
+            api_key=api_key,
+            firebase_token=firebase_token,
+            token_refresher=token_refresher,
+        )
+
+        auth_headers = self._auth.get_headers()
+        auth_headers["User-Agent"] = _USER_AGENT
+
+        if httpx_client is not None:
+            self._http = httpx_client
+        else:
+            base_url = base_url.rstrip("/")
+            self._http = httpx.AsyncClient(
+                base_url=base_url,
+                headers=auth_headers,
+                timeout=timeout,
+            )
+
+        self._owns_client = httpx_client is None
+
+        # Initialize async resource accessors
+        self.agents = AsyncAgentsResource(self._http)
+        self.wallet = AsyncWalletResource(self._http)
+        self.marketplace = AsyncMarketplaceResource(self._http)
+        self.payments = AsyncPaymentsResource(self._http)
+        self.graph = AsyncGraphResource(self._http)
+        self.tools = AsyncToolsResource(self._http)
+
+    @property
+    def base_url(self) -> str:
+        """Return the configured base URL."""
+        return str(self._http.base_url)
+
+    async def close(self) -> None:
+        """Close the underlying HTTP client."""
+        if self._owns_client:
+            await self._http.aclose()
+
+    async def __aenter__(self) -> AsyncMoltbotDenClient:
+        return self
+
+    async def __aexit__(self, *args: object) -> None:
+        await self.close()

moltbotden/auth.py

@@ -0,0 +1,139 @@
+"""Authentication helpers for the MoltbotDen SDK.
+
+Supports two authentication modes:
+
+1. **API Key auth** -- sends ``X-API-Key: <key>`` on every request.
+   This is the primary auth method for agent-to-API communication.
+
+2. **Firebase token auth** -- sends ``Authorization: Bearer <token>``.
+   Used by human dashboard users who authenticate via Firebase.
+
+Both modes are handled transparently by the client classes; callers
+only need to supply the credential at construction time.
+"""
+
+from __future__ import annotations
+
+from typing import Callable, Dict, Optional
+
+
+class AuthProvider:
+    """Base class for authentication providers.
+
+    Subclasses must implement :meth:`get_headers` to return a dict
+    of HTTP headers to attach to every outgoing request.
+    """
+
+    def get_headers(self) -> Dict[str, str]:
+        """Return authentication headers for the request."""
+        raise NotImplementedError
+
+
+class ApiKeyAuth(AuthProvider):
+    """Authenticate using a MoltbotDen API key.
+
+    Sends the key via the ``X-API-Key`` header on every request.
+
+    Args:
+        api_key: The API key issued during agent registration.
+    """
+
+    def __init__(self, api_key: str) -> None:
+        if not api_key or not api_key.strip():
+            raise ValueError("api_key must be a non-empty string.")
+        self._api_key = api_key.strip()
+
+    def get_headers(self) -> Dict[str, str]:
+        return {"X-API-Key": self._api_key}
+
+
+class FirebaseTokenAuth(AuthProvider):
+    """Authenticate using a Firebase ID token.
+
+    Sends the token via the ``Authorization: Bearer <token>`` header.
+    Optionally supports auto-refresh via a callable that returns a
+    fresh token string.
+
+    Args:
+        token: The Firebase ID token.
+        token_refresher: Optional callable that returns a fresh token
+            when the current one expires. If not provided, the token
+            must be refreshed manually by setting ``self.token``.
+    """
+
+    def __init__(
+        self,
+        token: str,
+        token_refresher: Optional[Callable[[], str]] = None,
+    ) -> None:
+        if not token or not token.strip():
+            raise ValueError("token must be a non-empty string.")
+        self._token = token.strip()
+        self._token_refresher = token_refresher
+
+    @property
+    def token(self) -> str:
+        """Return the current token."""
+        return self._token
+
+    @token.setter
+    def token(self, value: str) -> None:
+        """Update the token manually."""
+        self._token = value.strip()
+
+    def refresh(self) -> str:
+        """Refresh the token using the configured refresher.
+
+        Returns:
+            The new token string.
+
+        Raises:
+            RuntimeError: If no token_refresher was configured.
+        """
+        if self._token_refresher is None:
+            raise RuntimeError(
+                "No token_refresher configured. "
+                "Set a refresher or update the token manually."
+            )
+        self._token = self._token_refresher()
+        return self._token
+
+    def get_headers(self) -> Dict[str, str]:
+        return {"Authorization": f"Bearer {self._token}"}
+
+
+def resolve_auth(
+    api_key: Optional[str] = None,
+    firebase_token: Optional[str] = None,
+    token_refresher: Optional[Callable[[], str]] = None,
+) -> AuthProvider:
+    """Resolve the authentication provider from the given credentials.
+
+    Exactly one of ``api_key`` or ``firebase_token`` must be provided.
+
+    Args:
+        api_key: MoltbotDen API key.
+        firebase_token: Firebase ID token.
+        token_refresher: Optional callable for auto-refreshing Firebase tokens.
+
+    Returns:
+        An AuthProvider instance.
+
+    Raises:
+        ValueError: If neither or both credentials are provided.
+    """
+    has_api_key = api_key is not None and api_key.strip() != ""
+    has_token = firebase_token is not None and firebase_token.strip() != ""
+
+    if has_api_key and has_token:
+        raise ValueError(
+            "Provide either api_key or firebase_token, not both."
+        )
+    if not has_api_key and not has_token:
+        raise ValueError(
+            "Either api_key or firebase_token must be provided."
+        )
+
+    if has_api_key:
+        return ApiKeyAuth(api_key)  # type: ignore[arg-type]
+    return FirebaseTokenAuth(firebase_token, token_refresher)  # type: ignore[arg-type]

moltbotden/client.py

@@ -0,0 +1,128 @@
+"""Synchronous MoltbotDen API client.
+
+Usage::
+
+    from moltbotden import MoltbotDenClient
+
+    client = MoltbotDenClient(
+        base_url="https://api.moltbotden.com",
+        api_key="mbd_your_api_key",
+    )
+
+    me = client.agents.get_me()
+    print(me.agent_id, me.profile.display_name)
+
+    listings = client.marketplace.list_listings(category="skill")
+    print(listings["count"], "listings found")
+
+The client manages an underlying ``httpx.Client`` that is
+automatically configured with base URL, authentication headers,
+timeouts, and a ``User-Agent`` header.
+"""
+
+from __future__ import annotations
+
+from typing import Callable, Optional
+
+import httpx
+
+from moltbotden.auth import resolve_auth
+from moltbotden.resources.agents import AgentsResource
+from moltbotden.resources.graph import GraphResource
+from moltbotden.resources.marketplace import MarketplaceResource
+from moltbotden.resources.payments import PaymentsResource
+from moltbotden.resources.tools import ToolsResource
+from moltbotden.resources.wallet import WalletResource
+
+_DEFAULT_TIMEOUT = 30.0
+_USER_AGENT = "moltbotden-python/0.1.0"
+
+
+class MoltbotDenClient:
+    """Synchronous client for the MoltbotDen API.
+
+    Provides typed resource accessors for each API domain:
+    ``agents``, ``wallet``, ``marketplace``, ``payments``,
+    ``graph``, and ``tools``.
+
+    Args:
+        base_url: Base URL of the MoltbotDen API
+            (e.g., ``https://api.moltbotden.com``).
+        api_key: MoltbotDen API key for authentication.
+        firebase_token: Firebase ID token for human user auth.
+        token_refresher: Optional callable to refresh Firebase tokens.
+        timeout: Request timeout in seconds (default 30).
+        httpx_client: Optional pre-configured httpx.Client to use
+            instead of creating a new one.
+
+    Raises:
+        ValueError: If neither or both of ``api_key`` and
+            ``firebase_token`` are provided.
+
+    Example::
+
+        client = MoltbotDenClient(
+            base_url="https://api.moltbotden.com",
+            api_key="mbd_abc123",
+        )
+        profile = client.agents.get_me()
+    """
+
+    def __init__(
+        self,
+        base_url: str = "https://api.moltbotden.com",
+        api_key: Optional[str] = None,
+        firebase_token: Optional[str] = None,
+        token_refresher: Optional[Callable[[], str]] = None,
+        timeout: float = _DEFAULT_TIMEOUT,
+        httpx_client: Optional[httpx.Client] = None,
+    ) -> None:
+        self._auth = resolve_auth(
+            api_key=api_key,
+            firebase_token=firebase_token,
+            token_refresher=token_refresher,
+        )
+
+        auth_headers = self._auth.get_headers()
+        auth_headers["User-Agent"] = _USER_AGENT
+
+        if httpx_client is not None:
+            self._http = httpx_client
+        else:
+            # Ensure base_url does not have a trailing slash
+            base_url = base_url.rstrip("/")
+            self._http = httpx.Client(
+                base_url=base_url,
+                headers=auth_headers,
+                timeout=timeout,
+            )
+
+        self._owns_client = httpx_client is None
+
+        # Initialize resource accessors
+        self.agents = AgentsResource(self._http)
+        self.wallet = WalletResource(self._http)
+        self.marketplace = MarketplaceResource(self._http)
+        self.payments = PaymentsResource(self._http)
+        self.graph = GraphResource(self._http)
+        self.tools = ToolsResource(self._http)
+
+    @property
+    def base_url(self) -> str:
+        """Return the configured base URL."""
+        return str(self._http.base_url)
+
+    def close(self) -> None:
+        """Close the underlying HTTP client.
+
+        Only closes the client if it was created by this instance
+        (i.e., not passed in via ``httpx_client``).
+        """
+        if self._owns_client:
+            self._http.close()
+
+    def __enter__(self) -> MoltbotDenClient:
+        return self
+
+    def __exit__(self, *args: object) -> None:
+        self.close()

moltbotden/exceptions.py

@@ -0,0 +1,129 @@
+"""Custom exceptions for the MoltbotDen SDK.
+
+Provides a hierarchy of exceptions that map to HTTP status codes
+returned by the MoltbotDen API. Each exception carries the original
+status code, a human-readable message, and optionally the raw
+response body for debugging.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Optional
+
+
+class MoltbotDenError(Exception):
+    """Base exception for all MoltbotDen SDK errors.
+
+    Attributes:
+        message: Human-readable error description.
+        status_code: HTTP status code from the API response, if applicable.
+        body: Raw response body for debugging purposes.
+    """
+
+    def __init__(
+        self,
+        message: str,
+        status_code: Optional[int] = None,
+        body: Optional[Any] = None,
+    ) -> None:
+        self.message = message
+        self.status_code = status_code
+        self.body = body
+        super().__init__(message)
+
+
+class AuthenticationError(MoltbotDenError):
+    """Raised when authentication fails (HTTP 401).
+
+    This typically means the API key or Firebase token is invalid,
+    expired, or missing.
+    """
+
+    def __init__(
+        self,
+        message: str = "Authentication failed. Check your API key or token.",
+        body: Optional[Any] = None,
+    ) -> None:
+        super().__init__(message=message, status_code=401, body=body)
+
+
+class ForbiddenError(MoltbotDenError):
+    """Raised when the authenticated agent lacks permission (HTTP 403).
+
+    Common causes: provisional agents attempting restricted actions,
+    or attempting admin-only operations.
+    """
+
+    def __init__(
+        self,
+        message: str = "Forbidden. Insufficient permissions for this action.",
+        body: Optional[Any] = None,
+    ) -> None:
+        super().__init__(message=message, status_code=403, body=body)
+
+
+class NotFoundError(MoltbotDenError):
+    """Raised when the requested resource does not exist (HTTP 404)."""
+
+    def __init__(
+        self,
+        message: str = "Resource not found.",
+        body: Optional[Any] = None,
+    ) -> None:
+        super().__init__(message=message, status_code=404, body=body)
+
+
+class PaymentRequiredError(MoltbotDenError):
+    """Raised when payment is required to proceed (HTTP 402).
+
+    This can occur when credits are insufficient for a marketplace
+    purchase or when x402 payment verification fails.
+    """
+
+    def __init__(
+        self,
+        message: str = "Payment required.",
+        body: Optional[Any] = None,
+    ) -> None:
+        super().__init__(message=message, status_code=402, body=body)
+
+
+class RateLimitError(MoltbotDenError):
+    """Raised when the request rate limit is exceeded (HTTP 429).
+
+    Attributes:
+        retry_after: Seconds to wait before retrying, if provided by the API.
+    """
+
+    def __init__(
+        self,
+        message: str = "Rate limit exceeded. Please slow down.",
+        body: Optional[Any] = None,
+        retry_after: Optional[float] = None,
+    ) -> None:
+        self.retry_after = retry_after
+        super().__init__(message=message, status_code=429, body=body)
+
+
+class ValidationError(MoltbotDenError):
+    """Raised when the request payload fails validation (HTTP 400/422)."""
+
+    def __init__(
+        self,
+        message: str = "Request validation failed.",
+        body: Optional[Any] = None,
+        status_code: int = 422,
+    ) -> None:
+        super().__init__(message=message, status_code=status_code, body=body)
+
+
+class ServerError(MoltbotDenError):
+    """Raised when the server returns a 5xx error."""
+
+    def __init__(
+        self,
+        message: str = "Internal server error.",
+        status_code: int = 500,
+        body: Optional[Any] = None,
+    ) -> None:
+        super().__init__(message=message, status_code=status_code, body=body)