driftstone 0.1.0__py3-none-any.whl

driftstone/__init__.py

@@ -0,0 +1,15 @@
+from .client import Driftstone
+from .exceptions import (
+    DriftstoneAPIError,
+    DriftstoneError,
+    DriftstoneHTTPError,
+    DriftstoneResponseError,
+)
+
+__all__ = [
+    "Driftstone",
+    "DriftstoneError",
+    "DriftstoneHTTPError",
+    "DriftstoneResponseError",
+    "DriftstoneAPIError",
+]

driftstone/_internal/__init__.py

@@ -0,0 +1 @@
+"""Internal Driftstone SDK implementation details."""

driftstone/_internal/constants.py

@@ -0,0 +1,7 @@
+DEFAULT_API_BASE_URL = "https://pickaxeproject--driftstone-api-api.modal.run"
+
+GCS_BUCKET_NAME = "driftstone"
+
+AVAILABLE_APP_TYPES = ("claude", "openclaw")
+
+AVAILABLE_CHANNEL_TYPES = ("api", "imessage")

driftstone/_internal/transport.py

@@ -0,0 +1,103 @@
+from __future__ import annotations
+
+from typing import Any, Literal, cast
+import httpx
+
+from .utils import logger
+from ..exceptions import (
+    DriftstoneAPIError, 
+    DriftstoneHTTPError, 
+    DriftstoneResponseError
+)
+
+Method = Literal["GET", "POST", "PUT", "PATCH", "DELETE"]
+
+class Transport:
+    def __init__(
+        self,
+        *,
+        base_url: str,
+        api_key: str,
+        timeout: float,
+        user_agent: str,
+        http_client: httpx.Client | None = None,
+    ) -> None:
+        self.timeout = timeout
+        self._headers = {
+            "Authorization": f"Bearer {api_key}",
+            "Content-Type": "application/json",
+            "Accept": "application/json",
+            "User-Agent": user_agent,
+        }
+        self._owns_http_client = http_client is None
+        self._http = http_client or httpx.Client(
+            base_url=base_url,
+            timeout=timeout,
+            headers=self._headers,
+        )
+
+    @property
+    def headers(self) -> dict[str, str]:
+        return self._headers.copy()
+
+    def close(self) -> None:
+        if self._owns_http_client:
+            self._http.close()
+
+    @staticmethod
+    def _parse_response(response: httpx.Response) -> dict[str, Any]:
+        try:
+            decoded = response.json()
+        except ValueError as exc:
+            raise DriftstoneResponseError(
+                f"Driftstone API returned non-JSON response (status={response.status_code})"
+            ) from exc
+
+        if not isinstance(decoded, dict):
+            raise DriftstoneResponseError(
+                "Driftstone API returned an unexpected response payload"
+            )
+
+        return cast(dict[str, Any], decoded)
+
+    def request(
+        self,
+        method: Method,
+        path: str,
+        payload: dict[str, Any] | None = None,
+    ) -> dict[str, Any]:
+        payload = payload or {}
+
+        try:
+            kwargs: dict[str, Any] = {
+                "method": method,
+                "url": path,
+                "headers": self._headers,
+            }
+            if method == "GET":
+                kwargs["params"] = payload
+            else:
+                kwargs["json"] = payload
+
+            response = self._http.request(**kwargs)
+        except httpx.HTTPError as exc:
+            raise DriftstoneHTTPError(f"HTTP request failed: {exc}") from exc
+
+        data = self._parse_response(response)
+
+        logger.debug(
+            "Received response from Driftstone API (status=%d, data=%s)",
+            response.status_code,
+            data,
+        )
+
+        if response.status_code >= 400:
+            raise DriftstoneAPIError(
+                f"Driftstone API returned error status {response.status_code}: {data}"
+            )
+
+        if data.get("success") is False:
+            message = str(data.get("error") or data.get("message") or "Request failed")
+            raise DriftstoneAPIError(f"Driftstone API error: {message}")
+
+        return data

driftstone/_internal/utils.py

@@ -0,0 +1,21 @@
+import logging
+import json
+
+logger = logging.getLogger("driftstone")
+logger.setLevel(logging.WARNING)
+logger.addHandler(logging.NullHandler())
+
+logging.basicConfig(
+    format="[%(funcName)s][%(asctime)s]: %(levelname)s %(message)s",
+    datefmt="%m/%d/%Y %H:%M:%S",
+)
+
+def set_debug(enabled: bool) -> None:
+    logger.setLevel(logging.INFO if enabled else logging.WARNING)
+
+def safe_parse_json(raw: str):
+    try:
+        return json.loads(raw)
+    except Exception as e:
+        logger.error("Failed to parse JSON: %s", e)
+        return None

driftstone/client.py

@@ -0,0 +1,67 @@
+from __future__ import annotations
+
+from typing import Any, Literal
+
+import httpx
+
+from ._internal.constants import DEFAULT_API_BASE_URL
+from ._internal.utils import logger, set_debug
+from ._internal.transport import Method, Transport
+from .resources.app import DriftstoneApp
+from .version import __version__
+
+class Driftstone:
+    def __init__(
+        self,
+        api_key: str,
+        *,
+        version: Literal["v1"] = "v1",
+        timeout: float = 30.0,
+        debug: bool = False,
+        http_client: httpx.Client | None = None,
+    ) -> None:
+        self.debug = debug
+        set_debug(self.debug)
+        
+        logger.info("Initializing Driftstone client with provided API key")
+
+        trimmed_key = api_key.strip()
+        if not trimmed_key:
+            raise ValueError("api_key must be provided")
+        if not trimmed_key.startswith("dk-"):
+            raise ValueError("Invalid Driftstone API key")
+
+        self.api_key = trimmed_key
+        self.version = version
+        self.timeout = timeout
+        self.base_url = f"{DEFAULT_API_BASE_URL}/{self.version}"
+
+        self._transport = Transport(
+            base_url=self.base_url,
+            api_key=self.api_key,
+            timeout=self.timeout,
+            user_agent=f"Driftstone-python/{__version__}",
+            http_client=http_client,
+        )
+
+    def close(self) -> None:
+        self._transport.close()
+
+    def __enter__(self) -> "Driftstone":
+        return self
+
+    def __exit__(self, *_: object) -> None:
+        self.close()
+
+    def _request(
+        self,
+        method: Method,
+        path: str,
+        payload: dict[str, Any] | None = None,
+    ) -> dict[str, Any]:
+        return self._transport.request(method, path, payload)
+
+    @property
+    def app(self) -> DriftstoneApp:
+        return DriftstoneApp(self)
+    

driftstone/exceptions.py

@@ -0,0 +1,14 @@
+class DriftstoneError(Exception):
+    """Base exception for the Driftstone SDK."""
+
+
+class DriftstoneHTTPError(DriftstoneError):
+    """Raised when the underlying HTTP request fails."""
+
+
+class DriftstoneResponseError(DriftstoneError):
+    """Raised when an API response cannot be parsed as expected."""
+
+
+class DriftstoneAPIError(DriftstoneError):
+    """Raised when the Driftstone API returns an error."""

driftstone/models/__init__.py

@@ -0,0 +1 @@
+"""Driftstone SDK models."""

driftstone/models/access_group.py

@@ -0,0 +1,32 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from datetime import datetime
+from typing import Any, Literal, Mapping
+
+AccessGroupLimitReset = Literal["daily", "monthly", "yearly"]
+
+
+@dataclass(frozen=True, slots=True)
+class DriftstoneAccessGroupModel:
+    id: str
+    appId: str
+    name: str
+    limit: int
+    limitReset: AccessGroupLimitReset
+    limitMessage: str
+    createdAt: datetime
+    updatedAt: datetime
+
+    @classmethod
+    def _from_api(cls, payload: Mapping[str, Any]) -> "DriftstoneAccessGroupModel":
+        return cls(
+            id=payload["id"],
+            appId=payload["appId"],
+            name=payload["name"],
+            limit=payload["limit"],
+            limitReset=payload["limitReset"],
+            limitMessage=payload["limitMessage"],
+            createdAt=datetime.fromisoformat(payload["createdAt"]),
+            updatedAt=datetime.fromisoformat(payload["updatedAt"]),
+        )

driftstone/models/app.py

@@ -0,0 +1,120 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from datetime import datetime
+from typing import (
+    TYPE_CHECKING, 
+    Any, 
+    Literal, 
+    Mapping, 
+    Optional, 
+    TypedDict,
+    Union,
+    Required,
+)
+
+if TYPE_CHECKING:
+    from ..resources.access_group import DriftstoneAccessGroup
+    from ..resources.version import DriftstoneVersion
+    from ..resources.channel import DriftstoneChannel
+    from ..resources.session import DriftstoneSession
+    from ..resources.profile import DriftstoneProfile
+    from ..resources.instance import DriftstoneInstance
+
+ApplicationType = Literal["claude", "openclaw"]
+
+class AppInitLimit(TypedDict):
+    name: Optional[str]
+    amount: Required[int]
+    interval: Required[Literal["daily", "weekly", "monthly"]]
+    message: Optional[str]
+
+class AppInitCredentialMCPOAuthNoneParam(TypedDict):
+    type: Required[Literal["none"]]
+
+class AppInitCredentialMCPOAuthBasicParam(TypedDict):
+    type: Required[Literal["client_secret_basic"]]
+    client_secret: Required[str]
+
+class AppInitCredentialMCPOAuthPostParam(TypedDict):
+    type: Required[Literal["client_secret_post"]]
+    client_secret: Required[str]
+
+class AppInitCredentialMCPOAuthRefresh(TypedDict):
+    client_id: Required[str]
+    refresh_token: Required[str]
+    token_endpoint: Required[str]
+    token_endpoint_auth: Required[Union[
+        AppInitCredentialMCPOAuthNoneParam,
+        AppInitCredentialMCPOAuthBasicParam,
+        AppInitCredentialMCPOAuthPostParam,
+    ]]
+    resource: Optional[str]
+    scope: Optional[str]
+
+class AppInitCredentialMCPOAuth(TypedDict):
+    access_token: Required[str]
+    mcp_server_url: Required[str]
+    type: Required[Literal["mcp_oauth"]]
+    expires_at: Optional[datetime]
+    refresh: Optional[AppInitCredentialMCPOAuthRefresh]
+
+class AppInitCredentialMCPStaticBearer(TypedDict):
+    token: Required[str]
+    mcp_server_url: Required[str]
+    type: Required[Literal["mcp_oauth"]]
+
+AppInitCredential = Union[AppInitCredentialMCPOAuth, AppInitCredentialMCPStaticBearer]
+
+@dataclass(frozen=True, slots=True)
+class DriftstoneAppModel:
+    id: str
+    orgId: str
+    type: ApplicationType
+    name: str
+    slug: str
+    vaultId: str
+    defaultAccessGroupId: str
+    headVersionId: Optional[str]
+    metadata: Optional[dict[str, str]]
+    createdAt: datetime
+    updatedAt: datetime
+
+    version: DriftstoneVersion
+    channel: DriftstoneChannel
+    session: DriftstoneSession
+    access_group: DriftstoneAccessGroup
+    profile: DriftstoneProfile
+    instance: DriftstoneInstance
+
+    @classmethod
+    def _from_api(
+        cls,
+        payload: Mapping[str, Any],
+        version: DriftstoneVersion,
+        channel: DriftstoneChannel,
+        session: DriftstoneSession,
+        access_group: DriftstoneAccessGroup,
+        profile: DriftstoneProfile,
+        instance: DriftstoneInstance,
+    ) -> "DriftstoneAppModel":
+        return cls(
+            id=payload["id"],
+            orgId=payload["orgId"],
+            type=payload["type"],
+            name=payload["name"],
+            slug=payload["slug"],
+            vaultId=payload["vaultId"],
+            defaultAccessGroupId=payload["defaultAccessGroupId"],
+            headVersionId=payload.get("headVersionId"),
+            metadata=payload.get("metadata"),
+            createdAt=datetime.fromisoformat(payload["createdAt"]),
+            updatedAt=datetime.fromisoformat(payload["updatedAt"]),
+            
+            version=version,
+            channel=channel,
+            session=session,
+            access_group=access_group,
+            profile=profile,
+            instance=instance,
+        )

driftstone/models/channel.py

@@ -0,0 +1,123 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from datetime import datetime
+from typing import (
+    Any,
+    AsyncIterator, 
+    Iterator, 
+    Literal,
+    Mapping, 
+    Optional, 
+    Protocol, 
+    TypedDict
+)
+
+from .response import ResponseRunStreamEvent
+
+ChannelType = Literal["api", "imessage"]
+
+class ChannelRun(Protocol):
+    def __call__(
+        self, 
+        user_id: str, 
+        session_id: Optional[str] = None,
+        input: str = ""
+    ) -> Iterator[ResponseRunStreamEvent]: ...
+
+class ChannelRunAsync(Protocol):
+    def __call__(
+        self, 
+        user_id: str, 
+        session_id: Optional[str] = None,
+        input: str = ""
+    ) -> AsyncIterator[ResponseRunStreamEvent]: ...
+
+class ChannelRunner(Protocol):
+    def __call__(
+        self, 
+        user_id: str, 
+        session_id: Optional[str] = None,
+        input: str = ""
+    ) -> Iterator[ResponseRunStreamEvent]: ...
+
+class ChannelRunnerAsync(Protocol):
+    def __call__(
+        self, 
+        user_id: str, 
+        session_id: Optional[str] = None,
+        input: str = ""
+    ) -> AsyncIterator[ResponseRunStreamEvent]: ...
+
+class ChannelAPIWebhook(TypedDict):
+    name: str
+    url: str
+    headers: Optional[dict[str, str]]
+
+class ChannelIMessageData(TypedDict):
+    sendBlueAPIKey: str
+    sendBlueSecretKey: str
+    fromNumber: str
+
+@dataclass(frozen=True, slots=True)
+class DriftstoneChannelModel:
+    id: str
+    appId: str
+    type: ChannelType
+    name: str
+    webhook: Optional[ChannelAPIWebhook]
+    data: Optional[ChannelIMessageData]
+    createdAt: datetime
+    updatedAt: datetime
+
+    run: ChannelRun
+    run_async: ChannelRunAsync
+
+    @classmethod
+    def _from_api(
+        cls, 
+        payload: Mapping[str, Any],
+        run: ChannelRunner,
+        run_async: ChannelRunnerAsync,
+    ) -> "DriftstoneChannelModel":
+        channel_id = payload["id"]
+
+        def channel_run(
+            user_id: str, 
+            session_id: Optional[str] = None,
+            input: str = ""
+        ) -> Iterator[ResponseRunStreamEvent]:
+            for event in run(
+                channel_id, 
+                user_id,
+                session_id,
+                input
+            ):
+                yield event
+
+        async def channel_run_async(
+            user_id: str, 
+            session_id: Optional[str] = None,
+            input: str = ""
+        ) -> AsyncIterator[ResponseRunStreamEvent]:
+            async for event in run_async(
+                channel_id, 
+                user_id, 
+                session_id,
+                input
+            ):
+                yield event
+
+        return cls(
+            id=payload["id"],
+            appId=payload["appId"],
+            type=payload["type"],
+            name=payload["name"],
+            webhook=payload.get("webhook"),
+            data=payload.get("data"),
+            createdAt=datetime.fromisoformat(payload["createdAt"]),
+            updatedAt=datetime.fromisoformat(payload["updatedAt"]),
+            
+            run=channel_run,
+            run_async=channel_run_async,
+        )

driftstone/models/instance.py

@@ -0,0 +1,51 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from datetime import datetime
+from typing import Any, Literal, Mapping, Optional
+
+InstanceStatus = Literal["running", "terminated"]
+
+@dataclass(frozen=True, slots=True)
+class DriftstoneInstanceModel:
+    id: str
+    appId: str
+    versionId: str
+    channelId: str
+    sessionId: str
+    profileId: str
+    accessGroupId: str
+    stateId: Optional[str]
+    identifier: str
+    timeout: int
+    totalCost: float
+    costBreakdown: dict[str, float]
+    tokenBreakdown: dict[str, int]
+    metadata: Optional[dict[str, str]]
+    status: InstanceStatus
+    error: Optional[str]
+    createdAt: datetime
+    updatedAt: datetime
+
+    @classmethod
+    def _from_api(cls, payload: Mapping[str, Any]) -> "DriftstoneInstanceModel":
+        return cls(
+            id=payload["id"],
+            appId=payload["appId"],
+            versionId=payload["versionId"],
+            channelId=payload["channelId"],
+            sessionId=payload["sessionId"],
+            profileId=payload["profileId"],
+            accessGroupId=payload["accessGroupId"],
+            stateId=payload.get("stateId"),
+            identifier=payload["identifier"],
+            timeout=payload["timeout"],
+            totalCost=payload["totalCost"],
+            costBreakdown=payload["costBreakdown"],
+            tokenBreakdown=payload["tokenBreakdown"],
+            metadata=payload.get("metadata"),
+            status=payload["status"],
+            error=payload.get("error"),
+            createdAt=datetime.fromisoformat(payload["createdAt"]),
+            updatedAt=datetime.fromisoformat(payload["updatedAt"]),
+        )

driftstone/models/profile.py

@@ -0,0 +1,61 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from datetime import datetime
+from typing import (
+    TYPE_CHECKING, 
+    Any, 
+    Mapping, 
+    Optional
+)
+
+if TYPE_CHECKING:
+    from ..resources.state import DriftstoneState
+
+@dataclass(frozen=True, slots=True)
+class DriftstoneProfileModel:
+    id: str
+    appId: str
+    identifier: str
+    currentSpending: float
+    totalSpending: float
+    headStateId: Optional[str]
+    initialChannelId: Optional[str]
+    accessGroupId: Optional[str]
+    lastResetAt: Optional[datetime]
+    createdAt: datetime
+    updatedAt: datetime
+
+    state: DriftstoneState
+
+    @staticmethod
+    def _parse_optional_datetime(value: Any) -> Optional[datetime]:
+        if value is None:
+            return None
+        if isinstance(value, datetime):
+            return value
+        if isinstance(value, str):
+            return datetime.fromisoformat(value)
+        raise ValueError("Expected datetime, ISO datetime string, or None")
+
+    @classmethod
+    def _from_api(
+        cls, 
+        payload: Mapping[str, Any],
+        state: DriftstoneState,
+    ) -> "DriftstoneProfileModel":
+        return cls(
+            id=payload["id"],
+            appId=payload["appId"],
+            identifier=payload["identifier"],
+            currentSpending=payload["currentSpending"],
+            totalSpending=payload["totalSpending"],
+            headStateId=payload.get("headStateId"),
+            initialChannelId=payload.get("initialChannelId"),
+            accessGroupId=payload.get("accessGroupId"),
+            lastResetAt=cls._parse_optional_datetime(payload.get("lastResetAt")),
+            createdAt=datetime.fromisoformat(payload["createdAt"]),
+            updatedAt=datetime.fromisoformat(payload["updatedAt"]),
+
+            state=state,
+        )

driftstone/models/response.py

@@ -0,0 +1,12 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Optional, Any
+
+@dataclass(frozen=True, slots=True)
+class ResponseRunStreamEvent:
+    instance_id: str
+    index: int
+    data: Any
+    done: Optional[bool] = None
+    error: Optional[str] = None

driftstone/models/session.py

@@ -0,0 +1,33 @@
+from __future__ import annotations
+
+from typing import Mapping, Any, Literal, Optional
+from dataclasses import dataclass
+from datetime import datetime
+
+SessionType = Literal["single", "multiple"]
+
+@dataclass(frozen=True, slots=True)
+class DriftstoneSessionModel:
+    id: str
+    appId: str
+    type: SessionType
+    userIds: list[str]
+    profileIds: list[str]
+    metadata: Optional[dict[str, str]]
+    externalId: Optional[str]
+    createdAt: datetime
+    updatedAt: datetime
+
+    @classmethod
+    def _from_api(cls, payload: Mapping[str, Any]) -> "DriftstoneSessionModel":
+        return cls(
+            id=payload["id"],
+            appId=payload["appId"],
+            type=payload["type"],
+            userIds=payload["userIds"],
+            profileIds=payload["profileIds"],
+            metadata=payload.get("metadata"),
+            externalId=payload.get("externalId"),
+            createdAt=datetime.fromisoformat(payload["createdAt"]),
+            updatedAt=datetime.fromisoformat(payload["updatedAt"]),
+        )