waveium 0.2.0__py3-none-any.whl

waveium/exceptions.py

@@ -0,0 +1,131 @@
+"""Exceptions for the Waveium SDK."""
+
+from typing import Any, Dict, Optional
+
+
+class WaveiumError(Exception):
+    """Base exception for all Waveium SDK errors."""
+
+    def __init__(
+        self,
+        message: str,
+        code: Optional[str] = None,
+        details: Optional[Dict[str, Any]] = None,
+    ) -> None:
+        """Initialize WaveiumError.
+
+        Args:
+            message: Error message
+            code: Optional error code from API
+            details: Optional additional error details
+        """
+        super().__init__(message)
+        self.message = message
+        self.code = code
+        self.details = details or {}
+
+    def __str__(self) -> str:
+        """Return string representation of error."""
+        if self.code:
+            return f"[{self.code}] {self.message}"
+        return self.message
+
+
+class AuthenticationError(WaveiumError):
+    """Raised when authentication fails (401)."""
+
+    pass
+
+
+class AuthorizationError(WaveiumError):
+    """Raised when user lacks permission for operation (403)."""
+
+    pass
+
+
+class ConflictError(WaveiumError):
+    """Raised when operation conflicts with resource state (409)."""
+
+    pass
+
+
+class NotFoundError(WaveiumError):
+    """Raised when a resource is not found (404)."""
+
+    pass
+
+
+class ValidationError(WaveiumError):
+    """Raised when request validation fails (400)."""
+
+    pass
+
+
+class RateLimitError(WaveiumError):
+    """Raised when rate limit is exceeded (429)."""
+
+    pass
+
+
+class APIError(WaveiumError):
+    """Raised for general API errors (500, 502, 503, etc.)."""
+
+    pass
+
+
+class NetworkError(WaveiumError):
+    """Raised when network communication fails."""
+
+    pass
+
+
+class FileUploadError(WaveiumError):
+    """Raised when file upload fails."""
+
+    pass
+
+
+class FileDownloadError(WaveiumError):
+    """Raised when file download fails."""
+
+    pass
+
+
+class ConfigurationError(WaveiumError):
+    """Raised when SDK configuration is invalid."""
+
+    pass
+
+
+class StreamError(WaveiumError):
+    """Base exception for SSE streaming errors."""
+
+    pass
+
+
+class StreamTimeoutError(StreamError):
+    """Raised when total stream duration exceeds the configured limit."""
+
+    pass
+
+
+class StreamReconnectError(StreamError):
+    """Raised when maximum SSE reconnection attempts are exceeded."""
+
+    pass
+
+
+class ExecutionFailedError(WaveiumError):
+    """Raised by wait() when an execution reaches 'failed' status."""
+
+    def __init__(
+        self,
+        message: str,
+        execution_id: str,
+        error_message: Optional[str] = None,
+        code: Optional[str] = None,
+        details: Optional[Dict[str, Any]] = None,
+    ) -> None:
+        super().__init__(message, code, details)
+        self.execution_id = execution_id
+        self.error_message = error_message

waveium/models/__init__.py

@@ -0,0 +1,224 @@
+"""Data models for the Waveium SDK."""
+
+from .auth import (
+    AuthTokenResponse,
+    CreateTokenRequest,
+    TokenExchangeResponse,
+    TokenListResponse,
+    TokenUser,
+)
+from .common import (
+    BaseWaveiumModel,
+    ErrorDetail,
+    ErrorResponse,
+    MessageResponse,
+    PaginationInfo,
+    StorageStatsResponse,
+)
+from .environments import (
+    BoundsInput,
+    CreateEnvironmentRequest,
+    CreateEnvironmentResponse,
+    EnvironmentListItem,
+    EnvironmentResponse,
+    EnvironmentUploadCompleteResponse,
+    EnvironmentUploadRequest,
+    EnvironmentUploadResponse,
+    PaginatedEnvironmentResponse,
+    RouteInput,
+    SimilarEnvironmentResponse,
+    UpdateEnvironmentRequest,
+)
+from .executions import (
+    CreateExecutionRequest,
+    ExecutionListItem,
+    ExecutionProgressResponse,
+    ExecutionResponse,
+    PaginatedExecutionResponse,
+    UpdateExecutionRequest,
+)
+from .files import (
+    ArchiveDownloadResponse,
+    BatchDownloadFile,
+    BatchDownloadResponse,
+    EnvironmentFilesResponse,
+    ExecutionFilesResponse,
+    FileDownloadResponse,
+    FileInfo,
+    SceneFilesResponse,
+)
+from .organizations import (
+    CreateOrganizationRequest,
+    OrganizationResponse,
+    OrganizationStatsResponse,
+    UpdateOrganizationRequest,
+)
+from .projects import (
+    AddProjectEnvironmentRequest,
+    AddProjectMemberRequest,
+    CreateProjectRequest,
+    PaginatedProjectEnvironmentResponse,
+    PaginatedProjectMemberResponse,
+    PaginatedProjectResponse,
+    ProjectEnvironmentResponse,
+    ProjectListItem,
+    ProjectMemberResponse,
+    ProjectResponse,
+    UpdateProjectMemberRequest,
+    UpdateProjectRequest,
+)
+from .roles import (
+    PermissionResponse,
+    RoleDetailResponse,
+    RolePermissionResponse,
+    RoleResponse,
+)
+from .scenes import (
+    CreateSceneRequest,
+    PaginatedSceneResponse,
+    PatchSceneRequest,
+    SceneListItem,
+    SceneParameters,
+    SceneResponse,
+    SceneUploadCompleteResponse,
+    SceneUploadRequest,
+    SceneUploadResponse,
+    SimilarSceneResponse,
+    UpdateSceneRequest,
+)
+from .shares import (
+    CreateShareRequest,
+    PaginatedShareResponse,
+    ShareResponse,
+)
+from .teams import (
+    AddTeamMemberRequest,
+    CreateTeamRequest,
+    PaginatedTeamMemberResponse,
+    PaginatedTeamResponse,
+    TeamMemberResponse,
+    TeamResponse,
+    UpdateTeamRequest,
+)
+from .events import (
+    ErrorEvent,
+    ExecutionProgress,
+    ServerEvent,
+    StatusEvent,
+    TimeoutEvent,
+)
+from .users import (
+    AdminUpdateUserRequest,
+    CreateUserRequest,
+    PaginatedUserResponse,
+    RoleInUserResponse,
+    UpdateOwnUserRequest,
+    UserResponse,
+    UserRoleResponse,
+)
+
+__all__ = [
+    # Common
+    "BaseWaveiumModel",
+    "ErrorDetail",
+    "ErrorResponse",
+    "MessageResponse",
+    "PaginationInfo",
+    "StorageStatsResponse",
+    # Auth
+    "AuthTokenResponse",
+    "CreateTokenRequest",
+    "TokenExchangeResponse",
+    "TokenListResponse",
+    "TokenUser",
+    # Environments
+    "BoundsInput",
+    "CreateEnvironmentRequest",
+    "CreateEnvironmentResponse",
+    "EnvironmentListItem",
+    "EnvironmentResponse",
+    "EnvironmentUploadCompleteResponse",
+    "EnvironmentUploadRequest",
+    "EnvironmentUploadResponse",
+    "PaginatedEnvironmentResponse",
+    "RouteInput",
+    "SimilarEnvironmentResponse",
+    "UpdateEnvironmentRequest",
+    # Scenes
+    "CreateSceneRequest",
+    "PaginatedSceneResponse",
+    "PatchSceneRequest",
+    "SceneListItem",
+    "SceneParameters",
+    "SceneResponse",
+    "SceneUploadCompleteResponse",
+    "SceneUploadRequest",
+    "SceneUploadResponse",
+    "SimilarSceneResponse",
+    "UpdateSceneRequest",
+    # Executions
+    "CreateExecutionRequest",
+    "ExecutionListItem",
+    "ExecutionProgressResponse",
+    "ExecutionResponse",
+    "PaginatedExecutionResponse",
+    "UpdateExecutionRequest",
+    # Files
+    "ArchiveDownloadResponse",
+    "BatchDownloadFile",
+    "BatchDownloadResponse",
+    "EnvironmentFilesResponse",
+    "ExecutionFilesResponse",
+    "FileDownloadResponse",
+    "FileInfo",
+    "SceneFilesResponse",
+    # Organizations
+    "CreateOrganizationRequest",
+    "OrganizationResponse",
+    "OrganizationStatsResponse",
+    "UpdateOrganizationRequest",
+    # Projects
+    "AddProjectEnvironmentRequest",
+    "AddProjectMemberRequest",
+    "CreateProjectRequest",
+    "PaginatedProjectEnvironmentResponse",
+    "PaginatedProjectMemberResponse",
+    "PaginatedProjectResponse",
+    "ProjectEnvironmentResponse",
+    "ProjectListItem",
+    "ProjectMemberResponse",
+    "ProjectResponse",
+    "UpdateProjectMemberRequest",
+    "UpdateProjectRequest",
+    # Roles
+    "PermissionResponse",
+    "RoleDetailResponse",
+    "RolePermissionResponse",
+    "RoleResponse",
+    # Shares
+    "CreateShareRequest",
+    "PaginatedShareResponse",
+    "ShareResponse",
+    # Teams
+    "AddTeamMemberRequest",
+    "CreateTeamRequest",
+    "PaginatedTeamMemberResponse",
+    "PaginatedTeamResponse",
+    "TeamMemberResponse",
+    "TeamResponse",
+    "UpdateTeamRequest",
+    # Events (SSE)
+    "ErrorEvent",
+    "ExecutionProgress",
+    "ServerEvent",
+    "StatusEvent",
+    "TimeoutEvent",
+    # Users
+    "AdminUpdateUserRequest",
+    "CreateUserRequest",
+    "PaginatedUserResponse",
+    "RoleInUserResponse",
+    "UpdateOwnUserRequest",
+    "UserResponse",
+    "UserRoleResponse",
+]

waveium/models/auth.py

@@ -0,0 +1,58 @@
+"""Authentication models for the Waveium SDK."""
+
+from datetime import datetime
+from typing import List, Optional
+
+from pydantic import Field
+
+from .common import BaseWaveiumModel
+
+
+class CreateTokenRequest(BaseWaveiumModel):
+    """Request to create a new API token."""
+
+    name: str = Field(description="Name/description for the API key")
+    expires_days: int = Field(
+        default=30,
+        ge=1,
+        le=365,
+        description="Number of days until token expires (1-365)",
+    )
+
+
+class TokenUser(BaseWaveiumModel):
+    """User information included in token response."""
+
+    id: str = Field(description="User ID")
+    email: str = Field(description="User email")
+    name: Optional[str] = Field(default=None, description="User name")
+    organization_id: str = Field(description="Organization ID")
+
+
+class TokenExchangeResponse(BaseWaveiumModel):
+    """Response from token exchange endpoint."""
+
+    api_key: str = Field(description="Generated API key (only returned once)")
+    expires_in: int = Field(description="Expiration time in seconds")
+    user: TokenUser = Field(description="User information")
+
+
+class AuthTokenResponse(BaseWaveiumModel):
+    """Individual API token information."""
+
+    id: str = Field(description="Token ID")
+    name: str = Field(description="Token name/description")
+    is_active: bool = Field(description="Whether the token is active")
+    expires_at: Optional[datetime] = Field(
+        default=None, description="When the token expires"
+    )
+    created_at: datetime = Field(description="When the token was created")
+    last_used: Optional[datetime] = Field(
+        default=None, description="When the token was last used"
+    )
+
+
+class TokenListResponse(BaseWaveiumModel):
+    """Response containing list of tokens."""
+
+    tokens: List[AuthTokenResponse] = Field(description="List of tokens")

waveium/models/common.py

@@ -0,0 +1,130 @@
+"""Common models used across the Waveium SDK."""
+
+from datetime import datetime
+from typing import Any, Dict, List, Literal, Optional, Sequence  # noqa: F401
+
+from pydantic import BaseModel, Field
+
+
+class ErrorDetail(BaseModel):
+    """Error detail from API responses."""
+
+    code: str = Field(description="Error code")
+    message: str = Field(description="Error message")
+    details: Optional[Dict[str, Any]] = Field(
+        default=None, description="Additional error details"
+    )
+
+
+class ErrorResponse(BaseModel):
+    """Error response from the API."""
+
+    error: ErrorDetail = Field(description="Error information")
+
+
+class MessageResponse(BaseModel):
+    """Generic message response."""
+
+    message: str = Field(description="Response message")
+
+
+class PaginationInfo(BaseModel):
+    """Pagination information for list responses."""
+
+    page: int = Field(description="Current page number (1-based)")
+    page_size: int = Field(description="Items per page")
+    total: int = Field(description="Total number of items")
+    total_pages: int = Field(description="Total number of pages")
+    has_next: bool = Field(description="Whether there is a next page")
+    has_prev: bool = Field(description="Whether there is a previous page")
+
+
+class BaseWaveiumModel(BaseModel):
+    """Base model for all Waveium API models."""
+
+    model_config = {"populate_by_name": True, "use_enum_values": True}
+
+
+# Status type aliases
+EnvironmentStatus = Literal[
+    "pending",
+    "queued",
+    "running",
+    "completed",
+    "failed",
+    "cancelled",
+]
+SceneStatus = Literal[
+    "pending",
+    "pending_environment",
+    "queued",
+    "running",
+    "completed",
+    "failed",
+    "cancelled",
+]
+ExecutionStatus = Literal[
+    "queued",
+    "running",
+    "completed",
+    "failed",
+    "cancelled",
+]
+EnvironmentType = Literal["outdoor", "indoor", "underground"]
+ScopeFilter = Literal["mine", "shared", "org"]
+SceneScopeFilter = Literal["mine", "shared", "project", "org"]
+PermissionLevel = Literal["view", "use", "full"]
+ShareTargetType = Literal["user", "team", "organization"]
+ProjectRole = Literal["owner", "admin", "member"]
+TeamRole = Literal["member", "admin"]
+TransportMode = Literal["walk", "bike", "drive"]
+SubscriptionTier = Literal["free", "starter", "pro", "enterprise"]
+ProjectMemberType = Literal["user", "team"]
+
+
+class StorageStatsResponse(BaseModel):
+    """Storage statistics for a resource."""
+
+    total_files: int = Field(description="Total number of files")
+    total_size_bytes: int = Field(description="Total size in bytes")
+    total_size_mb: float = Field(description="Total size in megabytes")
+    objects: Optional[Dict[str, Any]] = Field(
+        default=None, description="Object file statistics"
+    )
+
+
+def _fmt_dt(dt: Optional[datetime]) -> str:
+    """Format a datetime for table display."""
+    if dt is None:
+        return "-"
+    return dt.strftime("%Y-%m-%d %H:%M")
+
+
+def _tabulate(
+    headers: Sequence[str],
+    rows: Sequence[Sequence[str]],
+) -> str:
+    """Render a simple aligned text table.
+
+    Args:
+        headers: Column header strings.
+        rows: List of row tuples (same length as headers).
+
+    Returns:
+        Formatted table string with aligned columns.
+    """
+    # Compute column widths from headers and data
+    widths = [len(h) for h in headers]
+    for row in rows:
+        for i, cell in enumerate(row):
+            widths[i] = max(widths[i], len(cell))
+
+    # Build format string
+    fmt = "  ".join(f"{{:<{w}}}" for w in widths)
+
+    lines = [fmt.format(*headers)]
+    lines.append("  ".join("-" * w for w in widths))
+    for row in rows:
+        lines.append(fmt.format(*row))
+
+    return "\n".join(lines)