waveium 0.2.0__py3-none-any.whl

waveium/__init__.py

@@ -0,0 +1,204 @@
+"""Waveium SDK for Python.
+
+Official Python client library for the Waveium API.
+
+Example:
+    >>> import waveium
+    >>> client = waveium.init(api_key="wvx_...")
+    >>> resp = client.environments.create(name="My Env")
+    >>> env = resp.environment
+"""
+
+from typing import Optional
+
+from ._config import get_firebase_token
+from .async_client import AsyncClient
+from .client import Client
+from .exceptions import (
+    APIError,
+    AuthenticationError,
+    AuthorizationError,
+    ConfigurationError,
+    ConflictError,
+    ExecutionFailedError,
+    FileDownloadError,
+    FileUploadError,
+    NetworkError,
+    NotFoundError,
+    RateLimitError,
+    StreamError,
+    StreamReconnectError,
+    StreamTimeoutError,
+    ValidationError,
+    WaveiumError,
+)
+
+# Expose key models
+from .models import (
+    CreateEnvironmentRequest,
+    CreateTokenRequest,
+    EnvironmentResponse,
+    ExecutionProgress,
+    ExecutionResponse,
+    SceneResponse,
+    ServerEvent,
+    StatusEvent,
+    TokenExchangeResponse,
+)
+
+__version__ = "0.2.0"
+
+__all__ = [
+    # Main clients
+    "Client",
+    "AsyncClient",
+    # Convenience functions
+    "init",
+    "auth",
+    # Exceptions
+    "WaveiumError",
+    "AuthenticationError",
+    "AuthorizationError",
+    "ConflictError",
+    "NotFoundError",
+    "ValidationError",
+    "RateLimitError",
+    "APIError",
+    "NetworkError",
+    "FileUploadError",
+    "FileDownloadError",
+    "ConfigurationError",
+    "StreamError",
+    "StreamTimeoutError",
+    "StreamReconnectError",
+    "ExecutionFailedError",
+    # Common models
+    "CreateEnvironmentRequest",
+    "CreateTokenRequest",
+    "EnvironmentResponse",
+    "ExecutionProgress",
+    "ExecutionResponse",
+    "SceneResponse",
+    "ServerEvent",
+    "StatusEvent",
+    "TokenExchangeResponse",
+    # Version
+    "__version__",
+]
+
+
+def init(
+    api_key: Optional[str] = None,
+    base_url: Optional[str] = None,
+    timeout: Optional[float] = None,
+    max_retries: Optional[int] = None,
+) -> Client:
+    """Initialize a Waveium client with an API key.
+
+    Args:
+        api_key: API key for authentication. If not
+            provided, will try to load from
+            WAVEIUM_API_KEY environment variable.
+        base_url: Base URL for the Waveium API.
+            Defaults to production URL.
+        timeout: Request timeout in seconds.
+            Defaults to 60.0.
+        max_retries: Maximum number of retries for
+            failed requests. Defaults to 3.
+
+    Returns:
+        Configured Waveium client
+
+    Raises:
+        ConfigurationError: If configuration is invalid
+
+    Example:
+        >>> import waveium
+        >>> client = waveium.init(api_key="wvx_...")
+        >>> resp = client.environments.create(
+        ...     name="Test"
+        ... )
+    """
+    return Client(
+        api_key=api_key,
+        base_url=base_url,
+        timeout=timeout,
+        max_retries=max_retries,
+    )
+
+
+def auth(
+    firebase_token: Optional[str] = None,
+    token_name: str = "Python SDK Token",
+    expires_days: int = 30,
+    base_url: Optional[str] = None,
+    timeout: Optional[float] = None,
+    max_retries: Optional[int] = None,
+) -> Client:
+    """Initialize a Waveium client by exchanging a
+    Firebase JWT for an API key.
+
+    Args:
+        firebase_token: Firebase JWT token. If not
+            provided, will try to load from
+            FIREBASE_TOKEN environment variable.
+        token_name: Name for the created API token.
+            Defaults to "Python SDK Token".
+        expires_days: Number of days until token
+            expires (1-365). Defaults to 30.
+        base_url: Base URL for the Waveium API.
+            Defaults to production URL.
+        timeout: Request timeout in seconds.
+            Defaults to 60.0.
+        max_retries: Maximum number of retries for
+            failed requests. Defaults to 3.
+
+    Returns:
+        Configured Waveium client with API key
+
+    Raises:
+        ConfigurationError: If no Firebase token
+            provided or found
+        AuthenticationError: If Firebase token is invalid
+
+    Example:
+        >>> import waveium
+        >>> client = waveium.auth(
+        ...     firebase_token="eyJ..."
+        ... )
+        >>> resp = client.environments.create(
+        ...     name="Test"
+        ... )
+    """
+    if firebase_token is None:
+        firebase_token = get_firebase_token()
+
+    if firebase_token is None:
+        raise ConfigurationError(
+            "Firebase token is required. Provide it via "
+            "firebase_token parameter or FIREBASE_TOKEN "
+            "environment variable."
+        )
+
+    temp_client = Client(
+        api_key=firebase_token,
+        base_url=base_url,
+        timeout=timeout,
+        max_retries=max_retries,
+    )
+
+    try:
+        response = temp_client.auth.create_token(
+            name=token_name,
+            expires_days=expires_days,
+            firebase_token=firebase_token,
+        )
+
+        return Client(
+            api_key=response.api_key,
+            base_url=base_url,
+            timeout=timeout,
+            max_retries=max_retries,
+        )
+    finally:
+        temp_client.close()

waveium/_config.py

@@ -0,0 +1,88 @@
+"""Configuration management for the Waveium SDK."""
+
+import os
+from typing import Optional
+
+from dotenv import load_dotenv
+
+from .exceptions import ConfigurationError
+
+# Load environment variables from .env file
+load_dotenv()
+
+# Default configuration
+DEFAULT_BASE_URL = "https://api.waveium.io"
+DEFAULT_TIMEOUT = 60.0
+DEFAULT_MAX_RETRIES = 3
+
+
+class Config:
+    """Configuration for Waveium SDK."""
+
+    def __init__(
+        self,
+        api_key: Optional[str] = None,
+        base_url: Optional[str] = None,
+        timeout: Optional[float] = None,
+        max_retries: Optional[int] = None,
+    ) -> None:
+        """Initialize configuration.
+
+        Args:
+            api_key: API key for authentication. If not provided,
+                will try to load from WAVEIUM_API_KEY or WAVEIUM_SDK_TOKEN
+                environment variable.
+            base_url: Base URL for the Waveium API.
+                Defaults to production URL.
+            timeout: Request timeout in seconds. Defaults to 60.0.
+            max_retries: Maximum number of retries for failed requests.
+                Defaults to 3.
+
+        Raises:
+            ConfigurationError: If no API key is provided or found
+                in environment.
+        """
+        self.api_key = (
+            api_key
+            or os.getenv("WAVEIUM_API_KEY")
+            or os.getenv("WAVEIUM_SDK_TOKEN")
+        )
+        self.base_url = base_url or os.getenv(
+            "WAVEIUM_BASE_URL", DEFAULT_BASE_URL
+        ).rstrip("/")
+        self.timeout = timeout or float(
+            os.getenv("WAVEIUM_TIMEOUT", str(DEFAULT_TIMEOUT))
+        )
+        self.max_retries = max_retries or int(
+            os.getenv("WAVEIUM_MAX_RETRIES", str(DEFAULT_MAX_RETRIES))
+        )
+
+    def validate(self) -> None:
+        """Validate configuration.
+
+        Raises:
+            ConfigurationError: If configuration is invalid.
+        """
+        if not self.api_key:
+            raise ConfigurationError(
+                "API key is required. Provide it via api_key parameter or "
+                "WAVEIUM_API_KEY/WAVEIUM_SDK_TOKEN environment variable."
+            )
+
+        if not self.base_url:
+            raise ConfigurationError("Base URL cannot be empty")
+
+        if self.timeout <= 0:
+            raise ConfigurationError("Timeout must be positive")
+
+        if self.max_retries < 0:
+            raise ConfigurationError("Max retries cannot be negative")
+
+
+def get_firebase_token() -> Optional[str]:
+    """Get Firebase token from environment variable.
+
+    Returns:
+        Firebase token if found, None otherwise.
+    """
+    return os.getenv("FIREBASE_TOKEN")

waveium/_http.py

@@ -0,0 +1,362 @@
+"""HTTP client wrappers for the Waveium SDK."""
+
+import logging
+from typing import (
+    Any,
+    Dict,
+    Optional,
+    Type,
+    TypeVar,
+    Union,
+    overload,
+)
+
+import httpx
+from pydantic import BaseModel, ValidationError as PydanticValidationError
+
+from ._config import Config
+from .exceptions import (
+    APIError,
+    AuthenticationError,
+    AuthorizationError,
+    ConflictError,
+    NetworkError,
+    NotFoundError,
+    RateLimitError,
+    ValidationError,
+    WaveiumError,
+)
+from .models.common import ErrorResponse
+
+T = TypeVar("T", bound=BaseModel)
+
+logger = logging.getLogger("waveium")
+
+
+def _build_headers(config: Config) -> Dict[str, str]:
+    """Build request headers from config.
+
+    Args:
+        config: Configuration object
+
+    Returns:
+        Dictionary of headers
+    """
+    headers = {
+        "User-Agent": "waveium-python/0.2.0",
+        "Content-Type": "application/json",
+    }
+    if config.api_key:
+        if config.api_key.startswith(("wv_", "wvx_")):
+            headers["X-API-Key"] = config.api_key
+        else:
+            headers["Authorization"] = f"Bearer {config.api_key}"
+    return headers
+
+
+def _handle_error_response(response: httpx.Response) -> WaveiumError:
+    """Convert HTTP error response to appropriate exception.
+
+    Args:
+        response: HTTP response object
+
+    Returns:
+        Appropriate WaveiumError subclass
+    """
+    try:
+        error_data = response.json()
+        error_response = ErrorResponse.model_validate(error_data)
+        message = error_response.error.message
+        code = error_response.error.code
+        details = error_response.error.details
+    except Exception:
+        message = response.text or f"HTTP {response.status_code}"
+        code = None
+        details = None
+
+    if response.status_code == 400:
+        return ValidationError(message, code, details)
+    elif response.status_code == 401:
+        return AuthenticationError(message, code, details)
+    elif response.status_code == 403:
+        return AuthorizationError(message, code, details)
+    elif response.status_code == 404:
+        return NotFoundError(message, code, details)
+    elif response.status_code == 409:
+        return ConflictError(message, code, details)
+    elif response.status_code == 429:
+        return RateLimitError(message, code, details)
+    else:
+        return APIError(message, code, details)
+
+
+class HTTPClient:
+    """Synchronous HTTP client for Waveium API."""
+
+    def __init__(self, config: Config) -> None:
+        """Initialize HTTP client.
+
+        Args:
+            config: Configuration object
+        """
+        self.config = config
+        self._client: Optional[httpx.Client] = None
+
+    def _get_client(self) -> httpx.Client:
+        """Get or create HTTP client instance.
+
+        Returns:
+            HTTP client instance
+        """
+        if self._client is None:
+            self._client = httpx.Client(
+                base_url=self.config.base_url,
+                timeout=self.config.timeout,
+                headers=_build_headers(self.config),
+            )
+        return self._client
+
+    @overload
+    def request(
+        self,
+        method: str,
+        path: str,
+        *,
+        json_data: Optional[Dict[str, Any]] = None,
+        params: Optional[Dict[str, Any]] = None,
+        headers: Optional[Dict[str, str]] = None,
+        response_model: Type[T],
+    ) -> T: ...
+
+    @overload
+    def request(
+        self,
+        method: str,
+        path: str,
+        *,
+        json_data: Optional[Dict[str, Any]] = None,
+        params: Optional[Dict[str, Any]] = None,
+        headers: Optional[Dict[str, str]] = None,
+        response_model: None = None,
+    ) -> Dict[str, Any]: ...
+
+    def request(
+        self,
+        method: str,
+        path: str,
+        *,
+        json_data: Optional[Dict[str, Any]] = None,
+        params: Optional[Dict[str, Any]] = None,
+        headers: Optional[Dict[str, str]] = None,
+        response_model: Optional[Type[T]] = None,
+    ) -> Union[T, Dict[str, Any]]:
+        """Make HTTP request.
+
+        Args:
+            method: HTTP method (GET, POST, PUT, DELETE, etc.)
+            path: API endpoint path
+            json_data: Optional JSON request body
+            params: Optional query parameters
+            headers: Optional additional headers
+            response_model: Optional Pydantic model to parse response
+
+        Returns:
+            Parsed response model or raw dictionary
+
+        Raises:
+            WaveiumError: If request fails
+        """
+        client = self._get_client()
+        logger.debug("%s %s", method, path)
+
+        try:
+            response = client.request(
+                method=method,
+                url=path,
+                json=json_data,
+                params=params,
+                headers=headers,
+            )
+            response.raise_for_status()
+
+            if response.status_code == 204:
+                return (
+                    {}
+                    if response_model is None
+                    else response_model.model_validate({})
+                )
+
+            response_data: Dict[str, Any] = response.json()
+
+            if response_model:
+                try:
+                    return response_model.model_validate(response_data)
+                except PydanticValidationError as e:
+                    raise ValidationError(
+                        f"Failed to parse response: {str(e)}",
+                        code="VALIDATION_ERROR",
+                        details={"errors": e.errors()},
+                    )
+
+            return response_data
+
+        except httpx.HTTPStatusError as e:
+            logger.debug("%s %s -> %d", method, path, e.response.status_code)
+            raise _handle_error_response(e.response)
+        except httpx.RequestError as e:
+            logger.debug("%s %s -> network error: %s", method, path, e)
+            raise NetworkError(f"Network error: {str(e)}")
+        except Exception as e:
+            if isinstance(e, WaveiumError):
+                raise
+            raise APIError(f"Unexpected error: {str(e)}")
+
+    def close(self) -> None:
+        """Close HTTP client."""
+        if self._client:
+            self._client.close()
+            self._client = None
+
+    def __enter__(self) -> "HTTPClient":
+        """Enter context manager."""
+        return self
+
+    def __exit__(self, *args: Any) -> None:
+        """Exit context manager."""
+        self.close()
+
+
+class AsyncHTTPClient:
+    """Asynchronous HTTP client for Waveium API."""
+
+    def __init__(self, config: Config) -> None:
+        """Initialize async HTTP client.
+
+        Args:
+            config: Configuration object
+        """
+        self.config = config
+        self._client: Optional[httpx.AsyncClient] = None
+
+    def _get_client(self) -> httpx.AsyncClient:
+        """Get or create async HTTP client instance.
+
+        Returns:
+            Async HTTP client instance
+        """
+        if self._client is None:
+            self._client = httpx.AsyncClient(
+                base_url=self.config.base_url,
+                timeout=self.config.timeout,
+                headers=_build_headers(self.config),
+            )
+        return self._client
+
+    @overload
+    async def request(
+        self,
+        method: str,
+        path: str,
+        *,
+        json_data: Optional[Dict[str, Any]] = None,
+        params: Optional[Dict[str, Any]] = None,
+        headers: Optional[Dict[str, str]] = None,
+        response_model: Type[T],
+    ) -> T: ...
+
+    @overload
+    async def request(
+        self,
+        method: str,
+        path: str,
+        *,
+        json_data: Optional[Dict[str, Any]] = None,
+        params: Optional[Dict[str, Any]] = None,
+        headers: Optional[Dict[str, str]] = None,
+        response_model: None = None,
+    ) -> Dict[str, Any]: ...
+
+    async def request(
+        self,
+        method: str,
+        path: str,
+        *,
+        json_data: Optional[Dict[str, Any]] = None,
+        params: Optional[Dict[str, Any]] = None,
+        headers: Optional[Dict[str, str]] = None,
+        response_model: Optional[Type[T]] = None,
+    ) -> Union[T, Dict[str, Any]]:
+        """Make async HTTP request.
+
+        Args:
+            method: HTTP method (GET, POST, PUT, DELETE, etc.)
+            path: API endpoint path
+            json_data: Optional JSON request body
+            params: Optional query parameters
+            headers: Optional additional headers
+            response_model: Optional Pydantic model to parse response
+
+        Returns:
+            Parsed response model or raw dictionary
+
+        Raises:
+            WaveiumError: If request fails
+        """
+        client = self._get_client()
+        logger.debug("%s %s", method, path)
+
+        try:
+            response = await client.request(
+                method=method,
+                url=path,
+                json=json_data,
+                params=params,
+                headers=headers,
+            )
+            response.raise_for_status()
+
+            if response.status_code == 204:
+                return (
+                    {}
+                    if response_model is None
+                    else response_model.model_validate({})
+                )
+
+            response_data: Dict[str, Any] = response.json()
+
+            if response_model:
+                try:
+                    return response_model.model_validate(response_data)
+                except PydanticValidationError as e:
+                    raise ValidationError(
+                        f"Failed to parse response: {str(e)}",
+                        code="VALIDATION_ERROR",
+                        details={"errors": e.errors()},
+                    )
+
+            return response_data
+
+        except httpx.HTTPStatusError as e:
+            logger.debug("%s %s -> %d", method, path, e.response.status_code)
+            raise _handle_error_response(e.response)
+        except httpx.RequestError as e:
+            logger.debug("%s %s -> network error: %s", method, path, e)
+            raise NetworkError(f"Network error: {str(e)}")
+        except Exception as e:
+            if isinstance(e, WaveiumError):
+                raise
+            raise APIError(f"Unexpected error: {str(e)}")
+
+    async def close(self) -> None:
+        """Close async HTTP client."""
+        if self._client:
+            await self._client.aclose()
+            self._client = None
+
+    async def __aenter__(self) -> "AsyncHTTPClient":
+        """Enter async context manager."""
+        return self
+
+    async def __aexit__(self, *args: Any) -> None:
+        """Exit async context manager."""
+        await self.close()