getstack 0.1.0__py3-none-any.whl

getstack/__init__.py

@@ -0,0 +1,233 @@
+"""STACK Python SDK — trust infrastructure for AI agents.
+
+Usage::
+
+    from getstack import Stack
+
+    stack = Stack(api_key="sk_live_...")
+    agent = stack.agents.register("my-agent")
+
+    with stack.passports.mission(
+        agent_id=agent.id,
+        intent="Process invoices",
+        services=["slack", "stripe"],
+    ) as mission:
+        mission.log("slack", "read_channel", "#invoices")
+        mission.log("stripe", "create_invoice")
+
+For OAuth auth::
+
+    stack = Stack.from_oauth(
+        client_id="...",
+        client_secret="...",
+        access_token="...",
+        refresh_token="...",
+    )
+
+For async usage::
+
+    from getstack import AsyncStack
+
+    stack = AsyncStack(api_key="sk_live_...")
+"""
+
+from __future__ import annotations
+
+from .auth import ApiKeyAuth, SessionAuth, OAuthAuth
+from .client import HttpClient, AsyncHttpClient, DEFAULT_BASE_URL
+from .agents import AgentService
+from .passports import PassportService, Mission
+from .credentials import CredentialService
+from .services import ServiceService
+from .dropoffs import DropoffService
+from .reviews import ReviewService
+from .notifications import NotificationService
+from .audit import AuditService
+from .types import (
+    Agent,
+    Passport,
+    CheckpointResult,
+    CheckoutResult,
+    ReviewFlag,
+    PassportReport,
+    ReviewQueue,
+    ReviewQueueItem,
+    ReviewDecisionResult,
+    Credential,
+    NotificationChannel,
+    ToolCall,
+)
+from .errors import (
+    StackError,
+    NotFoundError,
+    UnauthorizedError,
+    ForbiddenError,
+    ValidationError,
+    PassportBlockedError,
+)
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "Stack",
+    "AsyncStack",
+    "__version__",
+    # Types
+    "Agent",
+    "Passport",
+    "CheckpointResult",
+    "CheckoutResult",
+    "ReviewFlag",
+    "PassportReport",
+    "ReviewQueue",
+    "ReviewQueueItem",
+    "ReviewDecisionResult",
+    "Credential",
+    "NotificationChannel",
+    "Mission",
+    "ToolCall",
+    # Errors
+    "StackError",
+    "NotFoundError",
+    "UnauthorizedError",
+    "ForbiddenError",
+    "ValidationError",
+    "PassportBlockedError",
+]
+
+
+class Stack:
+    """Synchronous STACK client.
+
+    Args:
+        api_key: A STACK API key (``sk_live_...``).
+        base_url: Override the API base URL.
+        timeout: HTTP timeout in seconds.
+    """
+
+    def __init__(
+        self,
+        api_key: str | None = None,
+        *,
+        base_url: str = DEFAULT_BASE_URL,
+        timeout: float = 30.0,
+        _auth: ApiKeyAuth | SessionAuth | OAuthAuth | None = None,
+    ):
+        if _auth:
+            auth = _auth
+        elif api_key:
+            auth = ApiKeyAuth(api_key)
+        else:
+            raise ValueError("Either api_key or _auth must be provided")
+
+        self._client = HttpClient(auth, base_url=base_url, timeout=timeout)
+        self.agents = AgentService(self._client)
+        self.passports = PassportService(self._client)
+        self.credentials = CredentialService(self._client)
+        self.services = ServiceService(self._client)
+        self.dropoffs = DropoffService(self._client)
+        self.reviews = ReviewService(self._client)
+        self.notifications = NotificationService(self._client)
+        self.audit = AuditService(self._client)
+
+    @classmethod
+    def from_session(cls, session_token: str, **kwargs) -> Stack:
+        """Create a client authenticated with a session JWT."""
+        return cls(_auth=SessionAuth(session_token), **kwargs)
+
+    @classmethod
+    def from_oauth(
+        cls,
+        client_id: str,
+        client_secret: str,
+        access_token: str,
+        refresh_token: str,
+        token_endpoint: str = "https://api.getstack.run/v1/oauth/token",
+        **kwargs,
+    ) -> Stack:
+        """Create a client with OAuth tokens. Auto-refreshes when expired."""
+        auth = OAuthAuth(
+            client_id=client_id,
+            client_secret=client_secret,
+            access_token=access_token,
+            refresh_token=refresh_token,
+            token_endpoint=token_endpoint,
+        )
+        return cls(_auth=auth, **kwargs)
+
+    def close(self) -> None:
+        """Close the underlying HTTP client."""
+        self._client.close()
+
+    def __enter__(self) -> Stack:
+        return self
+
+    def __exit__(self, *args) -> None:
+        self.close()
+
+
+class AsyncStack:
+    """Asynchronous STACK client.
+
+    Uses httpx.AsyncClient under the hood. All service methods are sync
+    (they use the sync HttpClient wrapper) — for true async, the async
+    client needs async service modules. This provides the async HTTP
+    transport layer for future async service implementations.
+
+    Args:
+        api_key: A STACK API key (``sk_live_...``).
+        base_url: Override the API base URL.
+        timeout: HTTP timeout in seconds.
+    """
+
+    def __init__(
+        self,
+        api_key: str | None = None,
+        *,
+        base_url: str = DEFAULT_BASE_URL,
+        timeout: float = 30.0,
+        _auth: ApiKeyAuth | SessionAuth | OAuthAuth | None = None,
+    ):
+        if _auth:
+            auth = _auth
+        elif api_key:
+            auth = ApiKeyAuth(api_key)
+        else:
+            raise ValueError("Either api_key or _auth must be provided")
+
+        self._client = AsyncHttpClient(auth, base_url=base_url, timeout=timeout)
+
+    @classmethod
+    def from_session(cls, session_token: str, **kwargs) -> AsyncStack:
+        """Create an async client authenticated with a session JWT."""
+        return cls(_auth=SessionAuth(session_token), **kwargs)
+
+    @classmethod
+    def from_oauth(
+        cls,
+        client_id: str,
+        client_secret: str,
+        access_token: str,
+        refresh_token: str,
+        token_endpoint: str = "https://api.getstack.run/v1/oauth/token",
+        **kwargs,
+    ) -> AsyncStack:
+        """Create an async client with OAuth tokens. Auto-refreshes when expired."""
+        auth = OAuthAuth(
+            client_id=client_id,
+            client_secret=client_secret,
+            access_token=access_token,
+            refresh_token=refresh_token,
+            token_endpoint=token_endpoint,
+        )
+        return cls(_auth=auth, **kwargs)
+
+    async def close(self) -> None:
+        """Close the underlying HTTP client."""
+        await self._client.close()
+
+    async def __aenter__(self) -> AsyncStack:
+        return self
+
+    async def __aexit__(self, *args) -> None:
+        await self.close()

getstack/agents.py

@@ -0,0 +1,70 @@
+"""Agent management."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from .client import HttpClient
+from .types import Agent
+
+
+def _to_agent(data: dict[str, Any]) -> Agent:
+    return Agent(
+        id=data["id"],
+        operator_id=data["operator_id"],
+        name=data["name"],
+        description=data.get("description"),
+        status=data["status"],
+        accountability_mode=data.get("accountability_mode", "standard"),
+        on_warning=data.get("on_warning", "notify"),
+        on_critical=data.get("on_critical", "notify"),
+        passport_blocked=data.get("passport_blocked", False),
+        passport_blocked_reason=data.get("passport_blocked_reason"),
+        passport_blocked_at=data.get("passport_blocked_at"),
+        created_at=data["created_at"],
+        updated_at=data["updated_at"],
+    )
+
+
+class AgentService:
+    def __init__(self, client: HttpClient):
+        self._client = client
+
+    def register(
+        self,
+        name: str,
+        description: str | None = None,
+        accountability_mode: str = "enforced",
+        on_warning: str = "notify",
+        on_critical: str = "notify",
+    ) -> Agent:
+        body: dict[str, Any] = {"name": name, "accountability_mode": accountability_mode}
+        if description:
+            body["description"] = description
+        if on_warning != "notify":
+            body["on_warning"] = on_warning
+        if on_critical != "notify":
+            body["on_critical"] = on_critical
+        return _to_agent(self._client.post("/v1/agents/register", json=body))
+
+    def get(self, agent_id: str) -> Agent:
+        return _to_agent(self._client.get(f"/v1/agents/{agent_id}"))
+
+    def list(self) -> list[Agent]:
+        data = self._client.get("/v1/agents")
+        return [_to_agent(a) for a in data]
+
+    def update(self, agent_id: str, **kwargs: Any) -> Agent:
+        return _to_agent(self._client.patch(f"/v1/agents/{agent_id}", json=kwargs))
+
+    def suspend(self, agent_id: str) -> Agent:
+        return self.update(agent_id, status="suspended")
+
+    def activate(self, agent_id: str) -> Agent:
+        return self.update(agent_id, status="active")
+
+    def delete(self, agent_id: str) -> dict[str, Any]:
+        return self._client.delete(f"/v1/agents/{agent_id}")
+
+    def unblock(self, agent_id: str) -> dict[str, Any]:
+        return self._client.post(f"/v1/agents/{agent_id}/unblock")

getstack/audit.py

@@ -0,0 +1,26 @@
+"""Audit log access."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from .client import HttpClient
+
+
+class AuditService:
+    def __init__(self, client: HttpClient):
+        self._client = client
+
+    def list(
+        self,
+        page: int = 1,
+        limit: int = 50,
+        action: str | None = None,
+        agent_id: str | None = None,
+    ) -> list[dict[str, Any]]:
+        params: dict[str, str] = {"page": str(page), "limit": str(limit)}
+        if action:
+            params["action"] = action
+        if agent_id:
+            params["agent_id"] = agent_id
+        return self._client.get("/v1/audit", params=params)

getstack/auth.py

@@ -0,0 +1,78 @@
+"""Authentication strategies for the STACK SDK."""
+
+from __future__ import annotations
+
+import time
+from abc import ABC, abstractmethod
+
+import httpx
+
+
+class AuthStrategy(ABC):
+    """Base class for auth strategies."""
+
+    @abstractmethod
+    def get_headers(self) -> dict[str, str]:
+        """Return auth headers for API requests."""
+        ...
+
+
+class ApiKeyAuth(AuthStrategy):
+    """Authenticate with a STACK API key (sk_live_...)."""
+
+    def __init__(self, api_key: str):
+        self.api_key = api_key
+
+    def get_headers(self) -> dict[str, str]:
+        return {"Authorization": f"Bearer {self.api_key}"}
+
+
+class SessionAuth(AuthStrategy):
+    """Authenticate with a session JWT (dashboard integrations)."""
+
+    def __init__(self, session_token: str):
+        self.session_token = session_token
+
+    def get_headers(self) -> dict[str, str]:
+        return {"Authorization": f"Bearer {self.session_token}"}
+
+
+class OAuthAuth(AuthStrategy):
+    """Authenticate with OAuth tokens. Auto-refreshes when expired."""
+
+    def __init__(
+        self,
+        client_id: str,
+        client_secret: str,
+        access_token: str,
+        refresh_token: str,
+        token_endpoint: str = "https://api.getstack.run/v1/oauth/token",
+    ):
+        self.client_id = client_id
+        self.client_secret = client_secret
+        self.access_token = access_token
+        self.refresh_token = refresh_token
+        self.token_endpoint = token_endpoint
+        self.expires_at: float | None = None
+
+    def get_headers(self) -> dict[str, str]:
+        if self.expires_at and time.time() > self.expires_at - 30:
+            self._refresh()
+        return {"Authorization": f"Bearer {self.access_token}"}
+
+    def _refresh(self) -> None:
+        """Exchange refresh_token for a new access_token."""
+        resp = httpx.post(
+            self.token_endpoint,
+            data={
+                "grant_type": "refresh_token",
+                "refresh_token": self.refresh_token,
+                "client_id": self.client_id,
+                "client_secret": self.client_secret,
+            },
+        )
+        resp.raise_for_status()
+        data = resp.json()
+        self.access_token = data["access_token"]
+        self.refresh_token = data.get("refresh_token", self.refresh_token)
+        self.expires_at = time.time() + data.get("expires_in", 3600)

getstack/client.py

@@ -0,0 +1,102 @@
+"""HTTP client for the STACK API."""
+
+from __future__ import annotations
+
+from typing import Any
+
+import httpx
+
+from .auth import AuthStrategy
+from .errors import raise_for_status
+
+DEFAULT_BASE_URL = "https://api.getstack.run"
+
+
+class HttpClient:
+    """Synchronous HTTP client wrapping httpx."""
+
+    def __init__(self, auth: AuthStrategy, base_url: str = DEFAULT_BASE_URL, timeout: float = 30.0):
+        self.auth = auth
+        self.base_url = base_url.rstrip("/")
+        self._client = httpx.Client(timeout=timeout)
+
+    def request(self, method: str, path: str, json: Any = None, params: dict[str, Any] | None = None) -> Any:
+        headers = {
+            "Content-Type": "application/json",
+            **self.auth.get_headers(),
+        }
+
+        url = f"{self.base_url}{path}"
+        resp = self._client.request(method, url, json=json, params=params, headers=headers)
+
+        if resp.status_code >= 400:
+            try:
+                body = resp.json()
+            except Exception:
+                body = {"error": {"message": resp.text}}
+            raise_for_status(resp.status_code, body)
+
+        if resp.status_code == 204:
+            return None
+
+        return resp.json()
+
+    def get(self, path: str, params: dict[str, Any] | None = None) -> Any:
+        return self.request("GET", path, params=params)
+
+    def post(self, path: str, json: Any = None) -> Any:
+        return self.request("POST", path, json=json)
+
+    def patch(self, path: str, json: Any = None) -> Any:
+        return self.request("PATCH", path, json=json)
+
+    def delete(self, path: str) -> Any:
+        return self.request("DELETE", path)
+
+    def close(self) -> None:
+        self._client.close()
+
+
+class AsyncHttpClient:
+    """Asynchronous HTTP client wrapping httpx."""
+
+    def __init__(self, auth: AuthStrategy, base_url: str = DEFAULT_BASE_URL, timeout: float = 30.0):
+        self.auth = auth
+        self.base_url = base_url.rstrip("/")
+        self._client = httpx.AsyncClient(timeout=timeout)
+
+    async def request(self, method: str, path: str, json: Any = None, params: dict[str, Any] | None = None) -> Any:
+        headers = {
+            "Content-Type": "application/json",
+            **self.auth.get_headers(),
+        }
+
+        url = f"{self.base_url}{path}"
+        resp = await self._client.request(method, url, json=json, params=params, headers=headers)
+
+        if resp.status_code >= 400:
+            try:
+                body = resp.json()
+            except Exception:
+                body = {"error": {"message": resp.text}}
+            raise_for_status(resp.status_code, body)
+
+        if resp.status_code == 204:
+            return None
+
+        return resp.json()
+
+    async def get(self, path: str, params: dict[str, Any] | None = None) -> Any:
+        return await self.request("GET", path, params=params)
+
+    async def post(self, path: str, json: Any = None) -> Any:
+        return await self.request("POST", path, json=json)
+
+    async def patch(self, path: str, json: Any = None) -> Any:
+        return await self.request("PATCH", path, json=json)
+
+    async def delete(self, path: str) -> Any:
+        return await self.request("DELETE", path)
+
+    async def close(self) -> None:
+        await self._client.aclose()

getstack/credentials.py

@@ -0,0 +1,33 @@
+"""Credential retrieval."""
+
+from __future__ import annotations
+
+from typing import Any
+from urllib.parse import quote
+
+from .client import HttpClient
+from .types import Credential
+
+
+class CredentialService:
+    def __init__(self, client: HttpClient):
+        self._client = client
+
+    def get(self, provider: str, passport: Any | None = None) -> Credential:
+        headers_extra = {}
+        if passport and hasattr(passport, "token"):
+            headers_extra["X-Passport-Token"] = passport.token
+        data = self._client.get(f"/v1/credentials/{quote(provider)}")
+        return Credential(
+            provider=data["provider"],
+            credential=data.get("credential"),
+            credentials=data.get("credentials"),
+        )
+
+    def get_by_connection(self, connection_id: str) -> Credential:
+        data = self._client.get(f"/v1/credentials/by-connection/{connection_id}")
+        return Credential(
+            provider=data["provider"],
+            credential=data.get("credential"),
+            credentials=data.get("credentials"),
+        )

getstack/dropoffs.py

@@ -0,0 +1,43 @@
+"""Drop-off management."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from .client import HttpClient
+
+
+class DropoffService:
+    def __init__(self, client: HttpClient):
+        self._client = client
+
+    def create(
+        self,
+        from_agent_id: str,
+        to_agent_id: str,
+        schema: dict[str, Any],
+        ttl_seconds: int | None = None,
+        on_expire: str | None = None,
+    ) -> dict[str, Any]:
+        body: dict[str, Any] = {
+            "from_agent": from_agent_id,
+            "to_agent": to_agent_id,
+            "schema": schema,
+        }
+        if ttl_seconds:
+            body["ttl_seconds"] = ttl_seconds
+        if on_expire:
+            body["on_expire"] = on_expire
+        return self._client.post("/v1/dropoffs", json=body)
+
+    def deposit(self, dropoff_id: str, data: dict[str, Any], agent_id: str) -> dict[str, Any]:
+        return self._client.post(f"/v1/dropoffs/{dropoff_id}/deposit", json={"agent_id": agent_id, "payload": data})
+
+    def collect(self, dropoff_id: str, agent_id: str) -> dict[str, Any]:
+        return self._client.post(f"/v1/dropoffs/{dropoff_id}/collect", json={"agent_id": agent_id})
+
+    def get(self, dropoff_id: str) -> dict[str, Any]:
+        return self._client.get(f"/v1/dropoffs/{dropoff_id}")
+
+    def list(self) -> list[dict[str, Any]]:
+        return self._client.get("/v1/dropoffs")

getstack/errors.py

@@ -0,0 +1,56 @@
+"""STACK SDK error classes."""
+
+from __future__ import annotations
+
+
+class StackError(Exception):
+    """Base error for all STACK API errors."""
+
+    def __init__(self, message: str, code: str = "UNKNOWN", status_code: int = 500, details: dict | None = None):
+        super().__init__(message)
+        self.code = code
+        self.status_code = status_code
+        self.details = details or {}
+
+
+class NotFoundError(StackError):
+    def __init__(self, message: str = "Resource not found"):
+        super().__init__(message, "NOT_FOUND", 404)
+
+
+class UnauthorizedError(StackError):
+    def __init__(self, message: str = "Unauthorized"):
+        super().__init__(message, "UNAUTHORIZED", 401)
+
+
+class ForbiddenError(StackError):
+    def __init__(self, message: str = "Forbidden"):
+        super().__init__(message, "FORBIDDEN", 403)
+
+
+class ValidationError(StackError):
+    def __init__(self, message: str = "Validation failed", details: dict | None = None):
+        super().__init__(message, "VALIDATION_ERROR", 400, details)
+
+
+class PassportBlockedError(StackError):
+    def __init__(self, message: str = "Agent is blocked from passport issuance"):
+        super().__init__(message, "PASSPORT_BLOCKED", 403)
+
+
+# Map HTTP status codes to error classes
+_STATUS_MAP = {
+    401: UnauthorizedError,
+    403: ForbiddenError,
+    404: NotFoundError,
+}
+
+
+def raise_for_status(status_code: int, body: dict) -> None:
+    """Raise an appropriate StackError from an API error response."""
+    error = body.get("error", {})
+    message = error.get("message", f"API error: {status_code}")
+    code = error.get("code", "UNKNOWN")
+
+    cls = _STATUS_MAP.get(status_code, StackError)
+    raise cls(message)