oneclaw 0.1.0__py3-none-any.whl

oneclaw/__init__.py

@@ -0,0 +1,33 @@
+"""Official Python SDK for the 1Claw secrets management platform."""
+
+from oneclaw.client import OneclawClient, create_client
+from oneclaw.errors import (
+    ApprovalRequiredError,
+    AuthError,
+    NotFoundError,
+    OneclawError,
+    PaymentRequiredError,
+    RateLimitError,
+    ResourceLimitExceededError,
+    ServerError,
+    ValidationError,
+)
+from oneclaw.types import OneclawClientConfig, OneclawResponse
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "OneclawClient",
+    "create_client",
+    "OneclawClientConfig",
+    "OneclawResponse",
+    "OneclawError",
+    "AuthError",
+    "NotFoundError",
+    "PaymentRequiredError",
+    "RateLimitError",
+    "ResourceLimitExceededError",
+    "ValidationError",
+    "ServerError",
+    "ApprovalRequiredError",
+]

oneclaw/client.py

@@ -0,0 +1,148 @@
+"""Main client for the 1Claw Python SDK."""
+
+from __future__ import annotations
+
+from oneclaw.http_client import HttpClient
+from oneclaw.resources.agents import AgentsResource
+from oneclaw.resources.api_keys import ApiKeysResource
+from oneclaw.resources.approvals import ApprovalsResource
+from oneclaw.resources.audit import AuditResource
+from oneclaw.resources.auth import AuthResource
+from oneclaw.resources.billing import BillingResource
+from oneclaw.resources.chains import ChainsResource
+from oneclaw.resources.org import OrgResource
+from oneclaw.resources.platform import PlatformResource
+from oneclaw.resources.policies import PoliciesResource
+from oneclaw.resources.risk import RiskResource
+from oneclaw.resources.secrets import SecretsResource
+from oneclaw.resources.sharing import SharingResource
+from oneclaw.resources.signing_keys import SigningKeysResource
+from oneclaw.resources.treasury import TreasuryResource
+from oneclaw.resources.treasury_wallets import TreasuryWalletsResource
+from oneclaw.resources.vaults import VaultResource
+from oneclaw.resources.webhooks import WebhooksResource
+from oneclaw.types import OneclawClientConfig
+
+
+class OneclawClient:
+    """The main 1Claw SDK client.
+
+    All API resources are exposed as namespaced attributes for
+    discoverability.
+
+    Examples
+    --------
+    >>> from oneclaw import create_client
+    >>>
+    >>> # Agent with API key (auto-exchanges for JWT)
+    >>> client = create_client(api_key="ocv_...")
+    >>>
+    >>> # Pre-authenticated with JWT
+    >>> client = create_client(token="eyJ...")
+    >>>
+    >>> # Use resources
+    >>> vaults = client.vaults.list()
+    >>> secret = client.secrets.get(vault_id, "my-key")
+    """
+
+    def __init__(self, config: OneclawClientConfig) -> None:
+        self._http = HttpClient(config)
+
+        if (
+            config.api_key
+            and not config.token
+            and not config.agent_id
+            and not config.api_key.startswith("ocv_")
+        ):
+            self._auto_authenticate_user_key(config.api_key)
+
+        self.auth = AuthResource(self._http)
+        self.vaults = VaultResource(self._http)
+        self.secrets = SecretsResource(self._http)
+        self.agents = AgentsResource(self._http)
+        self.policies = PoliciesResource(self._http)
+        self.chains = ChainsResource(self._http)
+        self.sharing = SharingResource(self._http)
+        self.billing = BillingResource(self._http)
+        self.audit = AuditResource(self._http)
+        self.org = OrgResource(self._http)
+        self.api_keys = ApiKeysResource(self._http)
+        self.signing_keys = SigningKeysResource(self._http)
+        self.treasury = TreasuryResource(self._http)
+        self.treasury_wallets = TreasuryWalletsResource(self._http)
+        self.platform = PlatformResource(self._http)
+        self.approvals = ApprovalsResource(self._http)
+        self.webhooks = WebhooksResource(self._http)
+        self.risk = RiskResource(self._http)
+
+    def _auto_authenticate_user_key(self, api_key: str) -> None:
+        """Exchange a ``1ck_`` user API key for a JWT (fire-and-forget)."""
+        try:
+            resp = self._http.request(
+                "POST", "/v1/auth/api-key-token",
+                body={"api_key": api_key},
+                skip_auth=True,
+            )
+            if resp.data and resp.data.get("access_token"):
+                self._http.set_token(resp.data["access_token"])
+        except Exception:
+            pass
+
+    @property
+    def resolved_agent_id(self) -> str | None:
+        """Agent ID resolved from the token exchange (for key-only auth)."""
+        return self._http.resolved_agent_id
+
+    def close(self) -> None:
+        """Close the underlying HTTP connection pool."""
+        self._http.close()
+
+    def __enter__(self) -> OneclawClient:
+        return self
+
+    def __exit__(self, *args: object) -> None:
+        self.close()
+
+
+def create_client(
+    *,
+    base_url: str = "https://api.1claw.xyz",
+    token: str | None = None,
+    api_key: str | None = None,
+    agent_id: str | None = None,
+    timeout: float = 30.0,
+) -> OneclawClient:
+    """Create a new 1Claw SDK client.
+
+    Parameters
+    ----------
+    base_url : str
+        The 1Claw API base URL (default: ``https://api.1claw.xyz``).
+    token : str, optional
+        A pre-existing JWT to use for authentication.
+    api_key : str, optional
+        An API key (``ocv_`` for agents, ``1ck_`` for users).
+        Agent keys auto-exchange for JWTs and refresh before expiry.
+    agent_id : str, optional
+        The agent UUID (optional with ``ocv_`` keys — auto-discovered).
+    timeout : float
+        HTTP request timeout in seconds (default: 30).
+
+    Returns
+    -------
+    OneclawClient
+        A fully configured client instance.
+
+    Examples
+    --------
+    >>> client = create_client(api_key="ocv_abc123")
+    >>> vaults = client.vaults.list()
+    """
+    config = OneclawClientConfig(
+        base_url=base_url,
+        token=token,
+        api_key=api_key,
+        agent_id=agent_id,
+        timeout=timeout,
+    )
+    return OneclawClient(config)

oneclaw/errors.py

@@ -0,0 +1,124 @@
+"""Error types for the 1Claw Python SDK."""
+
+from __future__ import annotations
+
+import contextlib
+from typing import Any
+
+
+class OneclawError(Exception):
+    """Base error for all 1Claw SDK errors."""
+
+    def __init__(
+        self,
+        message: str,
+        status: int,
+        error_type: str = "unknown",
+        detail: str | None = None,
+    ) -> None:
+        super().__init__(message)
+        self.status = status
+        self.error_type = error_type
+        self.detail = detail
+
+
+class AuthError(OneclawError):
+    """Raised on 401 Unauthorized or 403 Forbidden responses."""
+
+    def __init__(self, message: str, status: int = 401) -> None:
+        super().__init__(message, status, "auth_error")
+
+
+class ResourceLimitExceededError(OneclawError):
+    """Raised when a resource limit is exceeded (403 with type resource_limit_exceeded)."""
+
+    def __init__(self, message: str) -> None:
+        super().__init__(message, 403, "resource_limit_exceeded")
+
+
+class PaymentRequiredError(OneclawError):
+    """Raised on 402 Payment Required responses."""
+
+    def __init__(self, message: str, requirement: dict[str, Any] | None = None) -> None:
+        super().__init__(message, 402, "payment_required")
+        self.payment_requirement = requirement
+
+
+class ApprovalRequiredError(OneclawError):
+    """Raised when human approval is needed to access a resource."""
+
+    def __init__(self, approval_request_id: str, message: str | None = None) -> None:
+        super().__init__(
+            message or "Human approval is required to access this secret",
+            403,
+            "approval_required",
+        )
+        self.approval_request_id = approval_request_id
+
+
+class NotFoundError(OneclawError):
+    """Raised on 404 Not Found responses."""
+
+    def __init__(self, message: str = "Resource not found") -> None:
+        super().__init__(message, 404, "not_found")
+
+
+class RateLimitError(OneclawError):
+    """Raised on 429 Too Many Requests. Includes retry timing when available."""
+
+    def __init__(
+        self,
+        message: str = "Rate limit exceeded",
+        retry_after_ms: int | None = None,
+    ) -> None:
+        super().__init__(message, 429, "rate_limit")
+        self.retry_after_ms = retry_after_ms
+
+
+class ValidationError(OneclawError):
+    """Raised on 400 Bad Request responses for validation failures."""
+
+    def __init__(self, message: str, fields: dict[str, str] | None = None) -> None:
+        super().__init__(message, 400, "validation_error")
+        self.fields = fields
+
+
+class ServerError(OneclawError):
+    """Raised on 500+ server-side errors."""
+
+    def __init__(self, message: str = "Internal server error", status: int = 500) -> None:
+        super().__init__(message, status, "server_error")
+
+
+def error_from_response(
+    status: int,
+    body: dict[str, Any],
+    headers: dict[str, str] | None = None,
+) -> OneclawError:
+    """Parse an HTTP response into the appropriate typed error."""
+    message = body.get("detail") or body.get("message") or body.get("error") or f"HTTP {status}"
+
+    if status == 400:
+        return ValidationError(message, body.get("fields"))
+    if status == 401:
+        return AuthError(message, 401)
+    if status == 403:
+        error_type = body.get("type", "")
+        if error_type == "resource_limit_exceeded":
+            return ResourceLimitExceededError(message)
+        if error_type == "approval_required":
+            return ApprovalRequiredError(body.get("approval_request_id", ""), message)
+        return AuthError(message, 403)
+    if status == 402:
+        return PaymentRequiredError(message, body)
+    if status == 404:
+        return NotFoundError(message)
+    if status == 429:
+        retry_after_ms = None
+        if headers and "retry-after" in headers:
+            with contextlib.suppress(ValueError):
+                retry_after_ms = int(headers["retry-after"]) * 1000
+        return RateLimitError(message, retry_after_ms)
+    if status >= 500:
+        return ServerError(message, status)
+    return OneclawError(message, status, "unknown")

oneclaw/http_client.py

@@ -0,0 +1,242 @@
+"""Internal HTTP transport for the 1Claw Python SDK."""
+
+from __future__ import annotations
+
+import base64
+import json
+import threading
+import time
+from typing import Any, TypeVar
+
+import httpx
+
+from oneclaw.errors import OneclawError, error_from_response
+from oneclaw.types import ErrorInfo, OneclawClientConfig, OneclawResponse, ResponseMeta
+
+T = TypeVar("T")
+
+_REFRESH_BUFFER_SECS = 60
+
+
+class HttpClient:
+    """Low-level HTTP client that handles authentication and error mapping.
+
+    All resource modules delegate requests through this class.
+    Agent ``ocv_`` API keys are automatically exchanged for JWTs and
+    refreshed 60 seconds before expiry.
+    """
+
+    def __init__(self, config: OneclawClientConfig) -> None:
+        self._base_url = config.base_url.rstrip("/")
+        self._token = config.token
+        self._token_expires_at: float = 0
+        self._timeout = config.timeout
+
+        self._agent_credentials: dict[str, str | None] | None = None
+        self._resolved_agent_id: str | None = None
+        self._refresh_lock = threading.Lock()
+
+        is_agent_key = (config.api_key or "").startswith("ocv_") or config.agent_id is not None
+        if config.api_key and is_agent_key:
+            self._agent_credentials = {
+                "agent_id": config.agent_id,
+                "api_key": config.api_key,
+            }
+
+        self._client = httpx.Client(
+            base_url=self._base_url,
+            timeout=self._timeout,
+            headers={"Content-Type": "application/json"},
+        )
+
+    # -- public helpers --------------------------------------------------------
+
+    @property
+    def resolved_agent_id(self) -> str | None:
+        if self._resolved_agent_id:
+            return self._resolved_agent_id
+        if self._agent_credentials:
+            return self._agent_credentials.get("agent_id")
+        return None
+
+    def set_token(self, token: str) -> None:
+        self._token = token
+        self._token_expires_at = self._decode_expiry(token)
+
+    def get_token(self) -> str | None:
+        return self._token
+
+    @property
+    def base_url(self) -> str:
+        return self._base_url
+
+    # -- request methods -------------------------------------------------------
+
+    def request(
+        self,
+        method: str,
+        path: str,
+        *,
+        body: Any | None = None,
+        query: dict[str, Any] | None = None,
+        headers: dict[str, str] | None = None,
+        skip_auth: bool = False,
+    ) -> OneclawResponse[Any]:
+        """Perform a typed request and return an :class:`OneclawResponse` envelope."""
+        if not skip_auth:
+            self._ensure_token()
+
+        req_headers: dict[str, str] = {}
+        if headers:
+            req_headers.update(headers)
+        if not skip_auth and self._token:
+            req_headers["Authorization"] = f"Bearer {self._token}"
+
+        cleaned_query = None
+        if query:
+            cleaned_query = {k: str(v) for k, v in query.items() if v is not None}
+
+        try:
+            response = self._client.request(
+                method,
+                path,
+                json=body if body is not None else None,
+                params=cleaned_query,
+                headers=req_headers,
+            )
+        except httpx.HTTPError as exc:
+            return OneclawResponse(
+                data=None,
+                error=ErrorInfo(type="network_error", message=str(exc)),
+                meta=ResponseMeta(status=0),
+            )
+
+        if not response.is_success:
+            try:
+                err_body = response.json()
+            except Exception:
+                err_body = {}
+
+            err = error_from_response(
+                response.status_code,
+                err_body if isinstance(err_body, dict) else {},
+                dict(response.headers),
+            )
+            return OneclawResponse(
+                data=None,
+                error=ErrorInfo(type=err.error_type, message=str(err), detail=err.detail),
+                meta=ResponseMeta(status=response.status_code),
+            )
+
+        if response.status_code == 204:
+            return OneclawResponse(data=None, error=None, meta=ResponseMeta(status=204))
+
+        return OneclawResponse(
+            data=response.json(),
+            error=None,
+            meta=ResponseMeta(status=response.status_code),
+        )
+
+    def request_or_throw(
+        self,
+        method: str,
+        path: str,
+        *,
+        body: Any | None = None,
+        query: dict[str, Any] | None = None,
+        headers: dict[str, str] | None = None,
+    ) -> Any:
+        """Same as :meth:`request` but raises :class:`OneclawError` on failure."""
+        self._ensure_token()
+
+        req_headers: dict[str, str] = {}
+        if headers:
+            req_headers.update(headers)
+        if self._token:
+            req_headers["Authorization"] = f"Bearer {self._token}"
+
+        cleaned_query = None
+        if query:
+            cleaned_query = {k: str(v) for k, v in query.items() if v is not None}
+
+        response = self._client.request(
+            method,
+            path,
+            json=body if body is not None else None,
+            params=cleaned_query,
+            headers=req_headers,
+        )
+
+        if not response.is_success:
+            try:
+                err_body = response.json()
+            except Exception:
+                err_body = {}
+            raise error_from_response(
+                response.status_code,
+                err_body if isinstance(err_body, dict) else {},
+                dict(response.headers),
+            )
+
+        if response.status_code == 204:
+            return None
+
+        return response.json()
+
+    def close(self) -> None:
+        """Close the underlying HTTP connection pool."""
+        self._client.close()
+
+    # -- private helpers -------------------------------------------------------
+
+    def _ensure_token(self) -> None:
+        if not self._agent_credentials:
+            return
+        if self._token and time.time() < self._token_expires_at - _REFRESH_BUFFER_SECS:
+            return
+
+        with self._refresh_lock:
+            if self._token and time.time() < self._token_expires_at - _REFRESH_BUFFER_SECS:
+                return
+            self._refresh_agent_token()
+
+    def _refresh_agent_token(self) -> None:
+        assert self._agent_credentials is not None
+        payload: dict[str, Any] = {"api_key": self._agent_credentials["api_key"]}
+        if self._agent_credentials.get("agent_id"):
+            payload["agent_id"] = self._agent_credentials["agent_id"]
+
+        response = self._client.post(
+            "/v1/auth/agent-token",
+            json=payload,
+        )
+
+        if not response.is_success:
+            raise OneclawError(
+                f"Agent token refresh failed: HTTP {response.status_code}",
+                response.status_code,
+                "auth_error",
+            )
+
+        data = response.json()
+        self._token = data["access_token"]
+        self._token_expires_at = time.time() + data.get("expires_in", 3600)
+
+        if data.get("agent_id"):
+            self._resolved_agent_id = data["agent_id"]
+            if self._agent_credentials and not self._agent_credentials.get("agent_id"):
+                self._agent_credentials["agent_id"] = data["agent_id"]
+
+    @staticmethod
+    def _decode_expiry(jwt: str) -> float:
+        try:
+            parts = jwt.split(".")
+            if len(parts) != 3:
+                return 0
+            padding = 4 - len(parts[1]) % 4
+            padded = parts[1] + "=" * padding
+            payload = json.loads(base64.urlsafe_b64decode(padded))
+            exp = payload.get("exp")
+            return float(exp) if isinstance(exp, (int, float)) else 0
+        except Exception:
+            return 0

oneclaw/resources/__init__.py

@@ -0,0 +1,41 @@
+"""Resource modules for the 1Claw Python SDK."""
+
+from oneclaw.resources.agents import AgentsResource
+from oneclaw.resources.api_keys import ApiKeysResource
+from oneclaw.resources.approvals import ApprovalsResource
+from oneclaw.resources.audit import AuditResource
+from oneclaw.resources.auth import AuthResource
+from oneclaw.resources.billing import BillingResource
+from oneclaw.resources.chains import ChainsResource
+from oneclaw.resources.org import OrgResource
+from oneclaw.resources.platform import PlatformResource
+from oneclaw.resources.policies import PoliciesResource
+from oneclaw.resources.risk import RiskResource
+from oneclaw.resources.secrets import SecretsResource
+from oneclaw.resources.sharing import SharingResource
+from oneclaw.resources.signing_keys import SigningKeysResource
+from oneclaw.resources.treasury import TreasuryResource
+from oneclaw.resources.treasury_wallets import TreasuryWalletsResource
+from oneclaw.resources.vaults import VaultResource
+from oneclaw.resources.webhooks import WebhooksResource
+
+__all__ = [
+    "AuthResource",
+    "VaultResource",
+    "SecretsResource",
+    "AgentsResource",
+    "PoliciesResource",
+    "ChainsResource",
+    "SharingResource",
+    "BillingResource",
+    "AuditResource",
+    "OrgResource",
+    "ApiKeysResource",
+    "SigningKeysResource",
+    "TreasuryResource",
+    "TreasuryWalletsResource",
+    "PlatformResource",
+    "ApprovalsResource",
+    "WebhooksResource",
+    "RiskResource",
+]