caido-sdk-client 0.1.0__tar.gz

caido_sdk_client-0.1.0/PKG-INFO

@@ -0,0 +1,27 @@
+Metadata-Version: 2.3
+Name: caido-sdk-client
+Version: 0.1.0
+Summary: Client SDK for interacting with a Caido instance
+Author: Caido Labs Inc.
+Author-email: Caido Labs Inc. <dev@caido.io>
+Requires-Dist: caido-server-auth>=0.1.2
+Requires-Dist: gql[aiohttp,websockets]>=3.5.0
+Requires-Dist: pydantic>=2.11.0
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+
+<div align="center">
+  <img width="1000" alt="image" src="https://github.com/caido-community/.github/blob/main/content/banner.png?raw=true">
+
+  <br />
+  <br />
+  <a href="https://github.com/caido-community" target="_blank">Github</a>
+  <span>&nbsp;&nbsp;•&nbsp;&nbsp;</span>
+  <a href="https://developer.caido.io/" target="_blank">Documentation</a>
+  <span>&nbsp;&nbsp;•&nbsp;&nbsp;</span>
+  <a href="https://links.caido.io/www-discord" target="_blank">Discord</a>
+  <br />
+  <hr />
+</div>
+
+## 👋 Client SDK

caido_sdk_client-0.1.0/README.md

@@ -0,0 +1,15 @@
+<div align="center">
+  <img width="1000" alt="image" src="https://github.com/caido-community/.github/blob/main/content/banner.png?raw=true">
+
+  <br />
+  <br />
+  <a href="https://github.com/caido-community" target="_blank">Github</a>
+  <span>&nbsp;&nbsp;•&nbsp;&nbsp;</span>
+  <a href="https://developer.caido.io/" target="_blank">Documentation</a>
+  <span>&nbsp;&nbsp;•&nbsp;&nbsp;</span>
+  <a href="https://links.caido.io/www-discord" target="_blank">Discord</a>
+  <br />
+  <hr />
+</div>
+
+## 👋 Client SDK

caido_sdk_client-0.1.0/pyproject.toml

@@ -0,0 +1,26 @@
+[project]
+name = "caido-sdk-client"
+version = "0.1.0"
+description = "Client SDK for interacting with a Caido instance"
+readme = "README.md"
+authors = [{ name = "Caido Labs Inc.", email = "dev@caido.io" }]
+requires-python = ">=3.12"
+dependencies = [
+    "caido-server-auth>=0.1.2",
+    "gql[aiohttp,websockets]>=3.5.0",
+    "pydantic>=2.11.0",
+]
+
+[dependency-groups]
+dev = ["pytest>=8.0.0", "pytest-asyncio>=0.24.0"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+asyncio_default_fixture_loop_scope = "session"
+testpaths = ["tests"]
+# Run tests one at a time (no parallel workers); integration tests share one Caido instance
+addopts = ["-p", "no:xdist"]
+
+[build-system]
+requires = ["uv_build>=0.9.8,<0.10.0"]
+build-backend = "uv_build"

caido_sdk_client-0.1.0/src/caido_sdk_client/__init__.py

@@ -0,0 +1,191 @@
+"""Public package exports."""
+
+from caido_sdk_client.auth import (
+    AuthCacheFile,
+    AuthManager,
+    AuthOptions,
+    BrowserAuthOptions,
+    CachedToken,
+    FileTokenCache,
+    PATAuthOptions,
+    TokenAuthOptions,
+    TokenCache,
+    TokenPair,
+)
+from caido_sdk_client.client import Client, ConnectOptions, Health, ReadyOptions
+from caido_sdk_client.errors import (
+    BaseError,
+    InstanceNotReadyError,
+    NoViewerInResponseError,
+    UnsupportedViewerTypeError,
+    from_error,
+)
+from caido_sdk_client.graphql import GraphQLClient
+from caido_sdk_client.logger import ConsoleLogger, Logger
+from caido_sdk_client.rest import RestClient
+from caido_sdk_client.sdks import (
+    EnvironmentInstance,
+    EnvironmentSDK,
+    FilterSDK,
+    FindingSDK,
+    FindingsListBuilder,
+    HostedFileSDK,
+    InstanceSDK,
+    PluginPackage,
+    PluginSDK,
+    RequestSDK,
+    RequestsListBuilder,
+    ScopeSDK,
+    UserSDK,
+)
+from caido_sdk_client.types import (
+    AISettings,
+    AnalyticsSettings,
+    AnthropicAISetting,
+    CloudUser,
+    CreateEnvironmentOptions,
+    CreateFilterPresetOptions,
+    CreateFindingOptions,
+    CreateScopeOptions,
+    Cursor,
+    CursorLike,
+    Environment,
+    EnvironmentVariable,
+    EnvironmentVariableKind,
+    FilterPreset,
+    Finding,
+    GoogleAISetting,
+    GuestUser,
+    HostedFile,
+    Httpql,
+    HttpqlLike,
+    Id,
+    IdLike,
+    InstallPluginPackageOptions,
+    InstallPluginPackageSourceFile,
+    InstallPluginPackageSourceManifest,
+    InstanceSettings,
+    OnboardingSettings,
+    OpenAIAISetting,
+    OpenRouterAISetting,
+    Plugin,
+    PluginBackend,
+    PluginFrontend,
+    PluginWorkflow,
+    Request,
+    RequestGetOptions,
+    RequestMetadata,
+    RequestResponseOpt,
+    Response,
+    Scope,
+    ScriptUser,
+    SetAISettingsInput,
+    SetAnalyticsSettingsInput,
+    SetInstanceSettingsInput,
+    SetOnboardingSettingsInput,
+    SubscriptionEntitlement,
+    SubscriptionPlan,
+    UpdateEnvironmentOptions,
+    UpdateFilterPresetOptions,
+    UpdateFindingOptions,
+    UpdateScopeOptions,
+    UploadHostedFileOptions,
+    User,
+    UserIdentity,
+    UserProfile,
+    UserSubscription,
+)
+
+__all__ = [
+    "AISettings",
+    "AnalyticsSettings",
+    "AnthropicAISetting",
+    "AuthCacheFile",
+    "AuthManager",
+    "AuthOptions",
+    "BaseError",
+    "BrowserAuthOptions",
+    "CachedToken",
+    "Client",
+    "CloudUser",
+    "ConnectOptions",
+    "ConsoleLogger",
+    "CreateEnvironmentOptions",
+    "CreateFilterPresetOptions",
+    "CreateFindingOptions",
+    "CreateScopeOptions",
+    "Cursor",
+    "CursorLike",
+    "Environment",
+    "EnvironmentInstance",
+    "EnvironmentSDK",
+    "EnvironmentVariable",
+    "EnvironmentVariableKind",
+    "FileTokenCache",
+    "FilterPreset",
+    "FilterSDK",
+    "Finding",
+    "HostedFile",
+    "HostedFileSDK",
+    "FindingSDK",
+    "FindingsListBuilder",
+    "GoogleAISetting",
+    "GraphQLClient",
+    "GuestUser",
+    "Health",
+    "InstallPluginPackageOptions",
+    "InstallPluginPackageSourceFile",
+    "InstallPluginPackageSourceManifest",
+    "Httpql",
+    "HttpqlLike",
+    "Id",
+    "IdLike",
+    "InstanceNotReadyError",
+    "InstanceSDK",
+    "InstanceSettings",
+    "Plugin",
+    "PluginBackend",
+    "PluginFrontend",
+    "PluginPackage",
+    "PluginSDK",
+    "PluginWorkflow",
+    "Logger",
+    "NoViewerInResponseError",
+    "OnboardingSettings",
+    "OpenAIAISetting",
+    "OpenRouterAISetting",
+    "PATAuthOptions",
+    "ReadyOptions",
+    "Request",
+    "RequestGetOptions",
+    "RequestMetadata",
+    "RequestResponseOpt",
+    "RequestSDK",
+    "RequestsListBuilder",
+    "Response",
+    "RestClient",
+    "Scope",
+    "ScopeSDK",
+    "ScriptUser",
+    "SetAISettingsInput",
+    "SetAnalyticsSettingsInput",
+    "SetInstanceSettingsInput",
+    "SetOnboardingSettingsInput",
+    "SubscriptionEntitlement",
+    "SubscriptionPlan",
+    "TokenAuthOptions",
+    "TokenCache",
+    "TokenPair",
+    "UnsupportedViewerTypeError",
+    "UpdateEnvironmentOptions",
+    "UploadHostedFileOptions",
+    "UpdateFilterPresetOptions",
+    "UpdateFindingOptions",
+    "UpdateScopeOptions",
+    "User",
+    "UserIdentity",
+    "UserProfile",
+    "UserSDK",
+    "UserSubscription",
+    "from_error",
+]

caido_sdk_client-0.1.0/src/caido_sdk_client/auth/__init__.py

@@ -0,0 +1,27 @@
+"""Authentication module exports."""
+
+from caido_sdk_client.auth.cache import CachedToken, FileTokenCache, TokenCache
+from caido_sdk_client.auth.manager import AuthManager
+from caido_sdk_client.auth.types import (
+    AuthCacheFile,
+    AuthCacheOptions,
+    AuthOptions,
+    BrowserAuthOptions,
+    PATAuthOptions,
+    TokenAuthOptions,
+    TokenPair,
+)
+
+__all__ = [
+    "AuthCacheFile",
+    "AuthCacheOptions",
+    "AuthManager",
+    "AuthOptions",
+    "BrowserAuthOptions",
+    "CachedToken",
+    "FileTokenCache",
+    "PATAuthOptions",
+    "TokenAuthOptions",
+    "TokenCache",
+    "TokenPair",
+]

caido_sdk_client-0.1.0/src/caido_sdk_client/auth/cache/__init__.py

@@ -0,0 +1,6 @@
+"""Token cache exports."""
+
+from caido_sdk_client.auth.cache.file import FileTokenCache
+from caido_sdk_client.auth.cache.types import CachedToken, TokenCache
+
+__all__ = ["CachedToken", "FileTokenCache", "TokenCache"]

caido_sdk_client-0.1.0/src/caido_sdk_client/auth/cache/file.py

@@ -0,0 +1,71 @@
+"""File-based token cache."""
+
+from __future__ import annotations
+
+import json
+import os
+from pathlib import Path
+
+from caido_sdk_client.auth.cache.types import CachedToken
+from caido_sdk_client.logger import Logger
+
+
+class FileTokenCache:
+    def __init__(
+        self,
+        *,
+        path: str | None = None,
+        logger: Logger | None = None,
+    ) -> None:
+        self._path = path or ".caido-token.json"
+        self._logger = logger
+
+    async def load(self) -> CachedToken | None:
+        try:
+            resolved = self._resolve_path()
+            with open(resolved) as f:
+                parsed = json.load(f)
+
+            access_token = parsed.get("access_token")
+            if access_token is None:
+                return None
+
+            return CachedToken(
+                access_token=access_token,
+                refresh_token=parsed.get("refresh_token"),
+                expires_at=parsed.get("expires_at"),
+            )
+        except Exception:
+            if self._logger is not None:
+                self._logger.debug("Failed to load cached token from file")
+            return None
+
+    async def save(self, token: CachedToken) -> None:
+        try:
+            resolved = self._resolve_path()
+            Path(resolved).parent.mkdir(parents=True, exist_ok=True)
+
+            data = {
+                "access_token": token.access_token,
+                "refresh_token": token.refresh_token,
+                "expires_at": token.expires_at,
+            }
+            fd = os.open(resolved, os.O_WRONLY | os.O_CREAT | os.O_TRUNC, 0o600)
+            with os.fdopen(fd, "w") as f:
+                json.dump(data, f, indent=2)
+        except Exception:
+            if self._logger is not None:
+                self._logger.warn("Failed to save token cache to file")
+
+    async def clear(self) -> None:
+        try:
+            resolved = self._resolve_path()
+            os.unlink(resolved)
+        except Exception:
+            if self._logger is not None:
+                self._logger.warn("Failed to clear token cache file")
+
+    def _resolve_path(self) -> str:
+        if os.path.isabs(self._path):
+            return self._path
+        return os.path.join(os.getcwd(), self._path)

caido_sdk_client-0.1.0/src/caido_sdk_client/auth/cache/types.py

@@ -0,0 +1,19 @@
+"""Cache types for persisting authentication tokens."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Protocol
+
+
+@dataclass(slots=True)
+class CachedToken:
+    access_token: str
+    refresh_token: str | None = None
+    expires_at: str | None = None
+
+
+class TokenCache(Protocol):
+    async def load(self) -> CachedToken | None: ...
+    async def save(self, token: CachedToken) -> None: ...
+    async def clear(self) -> None: ...

caido_sdk_client-0.1.0/src/caido_sdk_client/auth/manager.py

@@ -0,0 +1,196 @@
+"""Authentication manager."""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from dataclasses import dataclass
+from datetime import datetime
+from typing import Any
+
+from caido_server_auth import (
+    AuthClient,
+    AuthClientOptions,
+    BrowserApprover,
+    PATApprover,
+    PATApproverOptions,
+)
+
+from caido_sdk_client.auth.cache.types import CachedToken, TokenCache
+from caido_sdk_client.auth.types import (
+    AuthOptions,
+    BrowserAuthOptions,
+    TokenAuthOptions,
+)
+from caido_sdk_client.auth.utils import is_pat_auth, resolve_cache
+from caido_sdk_client.errors.auth import TokenRefreshError
+from caido_sdk_client.logger import Logger
+
+
+@dataclass(slots=True)
+class _TokenState:
+    access_token: str
+    refresh_token: str | None = None
+    expires_at: datetime | None = None
+
+
+class AuthManager:
+    def __init__(
+        self,
+        instance_url: str,
+        logger: Logger,
+        auth_options: AuthOptions | None = None,
+    ) -> None:
+        self._instance_url = instance_url
+        self._logger = logger
+        self._auth_options = auth_options
+        self._cache: TokenCache | None = (
+            resolve_cache(auth_options.cache, logger)
+            if auth_options is not None and auth_options.cache is not None
+            else None
+        )
+
+        self._token_state: _TokenState | None = None
+        self._auth_client: Any = None
+        self._on_token_refresh_callbacks: set[Callable[[], None]] = set()
+
+    def get_access_token(self) -> str | None:
+        if self._token_state is None:
+            return None
+        return self._token_state.access_token
+
+    def can_refresh(self) -> bool:
+        return (
+            self._token_state is not None
+            and self._token_state.refresh_token is not None
+        )
+
+    def on_token_refresh(self, callback: Callable[[], None]) -> Callable[[], None]:
+        """Subscribe to token refresh events.
+
+        Returns an unsubscribe function.
+        """
+        self._on_token_refresh_callbacks.add(callback)
+
+        def unsubscribe() -> None:
+            self._on_token_refresh_callbacks.discard(callback)
+
+        return unsubscribe
+
+    def _notify_token_refresh(self) -> None:
+        for callback in self._on_token_refresh_callbacks:
+            try:
+                callback()
+            except Exception:
+                self._logger.warn("Error in token refresh callback")
+
+    async def authenticate(self) -> None:
+        auth = self._auth_options
+
+        cache = self._cache
+        if cache is not None:
+            self._logger.debug("Attempting to load cached token")
+            cached = await cache.load()
+            if cached is not None:
+                self._logger.info("Loaded token from cache")
+                self._token_state = _from_cached_token(cached)
+                self._notify_token_refresh()
+                return
+
+        if auth is not None and isinstance(auth, TokenAuthOptions):
+            self._logger.debug("Using provided token")
+            if isinstance(auth.token, str):
+                self._token_state = _TokenState(access_token=auth.token)
+            else:
+                self._token_state = _TokenState(
+                    access_token=auth.token.access_token,
+                    refresh_token=auth.token.refresh_token,
+                )
+            self._notify_token_refresh()
+            await self._maybe_cache_token()
+            return
+
+        self._logger.info("Starting authentication flow")
+        auth_client = self._get_or_create_auth_client()
+        token = await auth_client.start_authentication_flow()
+        self._apply_auth_token(token)
+        self._logger.info("Authentication flow completed")
+        await self._maybe_cache_token()
+
+    async def refresh(self) -> None:
+        refresh_token = self._token_state.refresh_token if self._token_state else None
+        if refresh_token is None:
+            raise TokenRefreshError()
+
+        self._logger.debug("Refreshing access token")
+        auth_client = self._get_or_create_auth_client()
+        token = await auth_client.refresh_token(refresh_token)
+        self._apply_auth_token(token)
+        self._logger.info("Access token refreshed")
+        await self._maybe_cache_token()
+        self._notify_token_refresh()
+
+    def _get_or_create_auth_client(self) -> Any:
+        if self._auth_client is None:
+            approver = self._create_approver()
+            self._auth_client = AuthClient(
+                AuthClientOptions(
+                    instance_url=self._instance_url,
+                    approver=approver,
+                )
+            )
+        return self._auth_client
+
+    def _create_approver(self) -> Any:
+        auth = self._auth_options
+
+        if auth is not None and is_pat_auth(auth):
+            return PATApprover(PATApproverOptions(pat=auth.pat))  # type: ignore[union-attr]
+
+        logger = self._logger
+        browser_auth = auth if isinstance(auth, BrowserAuthOptions) else None
+        on_request = (
+            browser_auth.on_request
+            if browser_auth is not None and browser_auth.on_request is not None
+            else lambda request: logger.info(
+                f"Please visit the following URL to authenticate: {request.verification_url}"
+            )
+        )
+        return BrowserApprover(on_request)
+
+    def _apply_auth_token(self, token: Any) -> None:
+        self._token_state = _TokenState(
+            access_token=token.access_token,
+            refresh_token=token.refresh_token,
+            expires_at=token.expires_at,
+        )
+        self._notify_token_refresh()
+
+    async def _maybe_cache_token(self) -> None:
+        cache = self._cache
+        token_state = self._token_state
+        if cache is None or token_state is None:
+            return
+        self._logger.debug("Saving token to cache")
+        await cache.save(_to_cached_token(token_state))
+
+
+def _to_cached_token(state: _TokenState) -> CachedToken:
+    return CachedToken(
+        access_token=state.access_token,
+        refresh_token=state.refresh_token,
+        expires_at=state.expires_at.isoformat()
+        if state.expires_at is not None
+        else None,
+    )
+
+
+def _from_cached_token(cached: CachedToken) -> _TokenState:
+    return _TokenState(
+        access_token=cached.access_token,
+        refresh_token=cached.refresh_token,
+        expires_at=(
+            datetime.fromisoformat(cached.expires_at)
+            if cached.expires_at is not None
+            else None
+        ),
+    )

caido_sdk_client-0.1.0/src/caido_sdk_client/auth/types.py

@@ -0,0 +1,61 @@
+"""Authentication option types."""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from dataclasses import dataclass
+from typing import Any, Union
+
+from caido_sdk_client.auth.cache.types import TokenCache
+
+
+@dataclass(frozen=True, slots=True)
+class AuthCacheFile:
+    """File-based cache configuration. Path is relative to cwd or absolute."""
+
+    file: str
+
+
+@dataclass(frozen=True, slots=True)
+class AuthCacheLocalStorage:
+    """LocalStorage-based cache configuration (browser only)."""
+
+    localstorage: str
+
+
+AuthCacheOptions = Union[AuthCacheFile, AuthCacheLocalStorage, TokenCache]
+
+
+@dataclass(frozen=True, slots=True)
+class TokenPair:
+    """A pair of access and refresh tokens."""
+
+    access_token: str
+    refresh_token: str | None = None
+
+
+@dataclass(frozen=True, slots=True)
+class PATAuthOptions:
+    """Authenticate using a Personal Access Token (PAT)."""
+
+    pat: str
+    cache: AuthCacheOptions | None = None
+
+
+@dataclass(frozen=True, slots=True)
+class TokenAuthOptions:
+    """Authenticate with a direct access token or token pair."""
+
+    token: str | TokenPair
+    cache: AuthCacheOptions | None = None
+
+
+@dataclass(frozen=True, slots=True)
+class BrowserAuthOptions:
+    """Authenticate via browser-based device code flow."""
+
+    on_request: Callable[[Any], None] | None = None
+    cache: AuthCacheOptions | None = None
+
+
+AuthOptions = Union[PATAuthOptions, TokenAuthOptions, BrowserAuthOptions]

caido_sdk_client-0.1.0/src/caido_sdk_client/auth/utils.py

@@ -0,0 +1,31 @@
+"""Authentication utility functions."""
+
+from __future__ import annotations
+
+from caido_sdk_client.auth.cache.file import FileTokenCache
+from caido_sdk_client.auth.cache.types import TokenCache
+from caido_sdk_client.auth.types import (
+    AuthCacheFile,
+    AuthCacheLocalStorage,
+    AuthCacheOptions,
+    AuthOptions,
+    PATAuthOptions,
+    TokenAuthOptions,
+)
+from caido_sdk_client.logger import Logger
+
+
+def is_pat_auth(auth: AuthOptions) -> bool:
+    return isinstance(auth, PATAuthOptions)
+
+
+def is_token_auth(auth: AuthOptions) -> bool:
+    return isinstance(auth, TokenAuthOptions)
+
+
+def resolve_cache(options: AuthCacheOptions, logger: Logger) -> TokenCache:
+    if isinstance(options, AuthCacheFile):
+        return FileTokenCache(path=options.file, logger=logger)
+    if isinstance(options, AuthCacheLocalStorage):
+        raise NotImplementedError("LocalStorage cache is not supported in Python")
+    return options