waveium 0.2.0__py3-none-any.whl

waveium/models/users.py

@@ -0,0 +1,88 @@
+"""User models for the Waveium SDK."""
+
+from datetime import datetime
+from typing import List, Optional
+
+from pydantic import BaseModel, Field
+
+from .common import PaginationInfo
+
+
+class CreateUserRequest(BaseModel):
+    """Request to create a user (admin only)."""
+
+    email: str = Field(description="User email")
+    organization_id: str = Field(description="Organization ID")
+    name: Optional[str] = Field(default=None, description="User name")
+    temporary_password: Optional[str] = Field(
+        default=None, description="Temporary password"
+    )
+
+
+class UpdateOwnUserRequest(BaseModel):
+    """Request to update own profile."""
+
+    email: Optional[str] = Field(default=None, description="New email")
+    name: Optional[str] = Field(default=None, description="New name")
+
+
+class AdminUpdateUserRequest(BaseModel):
+    """Request to update a user (admin only)."""
+
+    email: Optional[str] = Field(default=None, description="New email")
+    name: Optional[str] = Field(default=None, description="New name")
+    is_active: Optional[bool] = Field(default=None, description="Active status")
+    role_ids: Optional[List[str]] = Field(
+        default=None, description="Role IDs to assign"
+    )
+
+
+class RoleInUserResponse(BaseModel):
+    """Inline role info in user role response."""
+
+    id: str = Field(description="Role ID")
+    name: str = Field(description="Role name")
+    description: Optional[str] = Field(default=None, description="Description")
+    scope: str = Field(description="Scope")
+    is_system_role: bool = Field(description="Is system role")
+    created_at: datetime = Field(description="Created at")
+
+
+class UserRoleResponse(BaseModel):
+    """User role assignment."""
+
+    id: str = Field(description="User role ID")
+    role: RoleInUserResponse = Field(description="Role details")
+    scope_type: str = Field(description="Scope type")
+    scope_id: Optional[str] = Field(default=None, description="Scope ID")
+    granted_at: datetime = Field(description="Granted at")
+    expires_at: Optional[datetime] = Field(
+        default=None, description="Expires at"
+    )
+
+
+class UserResponse(BaseModel):
+    """User information."""
+
+    id: str = Field(description="User ID")
+    email: str = Field(description="Email")
+    name: Optional[str] = Field(default=None, description="Name")
+    organization_id: str = Field(description="Organization ID")
+    is_active: bool = Field(description="Active status")
+    created_at: datetime = Field(description="Created at")
+    updated_at: Optional[datetime] = Field(
+        default=None, description="Updated at"
+    )
+    last_login: Optional[datetime] = Field(
+        default=None, description="Last login"
+    )
+    user_roles: Optional[List[UserRoleResponse]] = Field(
+        default=None, description="User roles"
+    )
+
+
+class PaginatedUserResponse(BaseModel):
+    """Paginated user list."""
+
+    data: List[UserResponse] = Field(description="List of users")
+    pagination: PaginationInfo = Field(description="Pagination info")

waveium/resources/__init__.py

@@ -0,0 +1,41 @@
+"""API resources for the Waveium SDK."""
+
+from .auth import AsyncAuthResource, AuthResource
+from .environments import (
+    AsyncEnvironmentsResource,
+    EnvironmentsResource,
+)
+from .executions import (
+    AsyncExecutionsResource,
+    ExecutionsResource,
+)
+from .organizations import (
+    AsyncOrganizationsResource,
+    OrganizationsResource,
+)
+from .projects import AsyncProjectsResource, ProjectsResource
+from .roles import AsyncRolesResource, RolesResource
+from .scenes import AsyncScenesResource, ScenesResource
+from .teams import AsyncTeamsResource, TeamsResource
+from .users import AsyncUsersResource, UsersResource
+
+__all__ = [
+    "AuthResource",
+    "AsyncAuthResource",
+    "EnvironmentsResource",
+    "AsyncEnvironmentsResource",
+    "ScenesResource",
+    "AsyncScenesResource",
+    "ExecutionsResource",
+    "AsyncExecutionsResource",
+    "UsersResource",
+    "AsyncUsersResource",
+    "OrganizationsResource",
+    "AsyncOrganizationsResource",
+    "RolesResource",
+    "AsyncRolesResource",
+    "TeamsResource",
+    "AsyncTeamsResource",
+    "ProjectsResource",
+    "AsyncProjectsResource",
+]

waveium/resources/_base.py

@@ -0,0 +1,30 @@
+"""Base resource classes for the Waveium SDK."""
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from .._http import AsyncHTTPClient, HTTPClient
+
+
+class BaseResource:
+    """Base class for synchronous API resources."""
+
+    def __init__(self, http_client: "HTTPClient") -> None:
+        """Initialize base resource.
+
+        Args:
+            http_client: HTTP client instance
+        """
+        self._http = http_client
+
+
+class AsyncBaseResource:
+    """Base class for asynchronous API resources."""
+
+    def __init__(self, http_client: "AsyncHTTPClient") -> None:
+        """Initialize async base resource.
+
+        Args:
+            http_client: Async HTTP client instance
+        """
+        self._http = http_client

waveium/resources/_file_ops.py

@@ -0,0 +1,371 @@
+"""Reusable file operation mixins for resources."""
+
+import asyncio
+from pathlib import Path
+from typing import TYPE_CHECKING, Optional, Union
+
+import anyio
+import httpx
+
+from ..exceptions import FileDownloadError
+from ..models.files import (
+    BatchDownloadFile,
+    BatchDownloadResponse,
+    FileDownloadResponse,
+)
+
+if TYPE_CHECKING:
+    from .._http import AsyncHTTPClient, HTTPClient
+
+
+class FileOperations:
+    """Sync file operations for a resource."""
+
+    def __init__(self, http: "HTTPClient", base_path: str) -> None:
+        self._http = http
+        self._base_path = base_path
+
+    def list_files(
+        self,
+        resource_id: str,
+        subdir: Optional[str] = None,
+        response_model: type = None,  # type: ignore[assignment]
+    ) -> object:
+        """List files for a resource.
+
+        Args:
+            resource_id: The resource identifier.
+            subdir: Optional subdirectory filter.
+            response_model: Pydantic model for response.
+
+        Returns:
+            Parsed response object.
+        """
+        params = {}
+        if subdir:
+            params["subdir"] = subdir
+        return self._http.request(
+            "GET",
+            f"{self._base_path}/{resource_id}/files",
+            params=params if params else None,
+            response_model=response_model,
+        )
+
+    def get_download_url(
+        self, resource_id: str, file_id: str
+    ) -> FileDownloadResponse:
+        """Get a signed download URL for a file.
+
+        Args:
+            resource_id: The resource identifier.
+            file_id: The file identifier.
+
+        Returns:
+            Download URL response with signed URL.
+        """
+        return self._http.request(
+            "GET",
+            (f"{self._base_path}/{resource_id}" f"/files/{file_id}/download"),
+            response_model=FileDownloadResponse,
+        )
+
+    def download(
+        self,
+        resource_id: str,
+        file_id: str,
+        destination: Union[str, Path],
+    ) -> Path:
+        """Download a file to a local path.
+
+        Args:
+            resource_id: The resource identifier.
+            file_id: The file identifier.
+            destination: Local file path to write to.
+
+        Returns:
+            Path to the downloaded file.
+
+        Raises:
+            FileDownloadError: If download fails.
+        """
+        resp = self.get_download_url(resource_id, file_id)
+        destination = Path(destination)
+        destination.parent.mkdir(parents=True, exist_ok=True)
+        try:
+            with httpx.Client() as client:
+                r = client.request(
+                    method=resp.method,
+                    url=resp.download_url,
+                )
+                r.raise_for_status()
+                with open(destination, "wb") as f:
+                    f.write(r.content)
+            return destination
+        except Exception as e:
+            raise FileDownloadError(f"Failed to download file: {e}")
+
+    def read_bytes(
+        self,
+        resource_id: str,
+        file_id: str,
+    ) -> bytes:
+        """Read a file's content into memory.
+
+        Fetches the file via its signed download URL and
+        returns the raw bytes without writing to disk.
+        Suitable for small-to-medium files (configs, CSVs,
+        metadata). For large files, use download() instead.
+
+        Args:
+            resource_id: The resource identifier.
+            file_id: The file identifier.
+
+        Returns:
+            File content as bytes.
+
+        Raises:
+            FileDownloadError: If download fails.
+        """
+        resp = self.get_download_url(resource_id, file_id)
+        try:
+            with httpx.Client() as client:
+                r = client.request(
+                    method=resp.method,
+                    url=resp.download_url,
+                )
+                r.raise_for_status()
+                return r.content
+        except Exception as e:
+            raise FileDownloadError(f"Failed to read file: {e}")
+
+    def download_batch(
+        self,
+        resource_id: str,
+        destination_dir: Union[str, Path],
+        subdir: Optional[str] = None,
+    ) -> BatchDownloadResponse:
+        """Download all files for a resource.
+
+        Args:
+            resource_id: The resource identifier.
+            destination_dir: Local directory to write to.
+            subdir: Optional subdirectory filter.
+
+        Returns:
+            Batch download response metadata.
+
+        Raises:
+            FileDownloadError: If any download fails.
+        """
+        params = {}
+        if subdir:
+            params["subdir"] = subdir
+        batch: BatchDownloadResponse = self._http.request(
+            "POST",
+            f"{self._base_path}/{resource_id}/downloads",
+            params=params if params else None,
+            response_model=BatchDownloadResponse,
+        )
+        dest = Path(destination_dir)
+        dest.mkdir(parents=True, exist_ok=True)
+        with httpx.Client() as client:
+            for fi in batch.files:
+                try:
+                    r = client.request(
+                        method=fi.method,
+                        url=fi.download_url,
+                    )
+                    r.raise_for_status()
+                    fp = (dest / fi.filename).resolve()
+                    if not str(fp).startswith(str(dest.resolve())):
+                        raise FileDownloadError(
+                            f"Unsafe filename rejected: " f"{fi.filename}"
+                        )
+                    with open(fp, "wb") as f:
+                        f.write(r.content)
+                except FileDownloadError:
+                    raise
+                except Exception as e:
+                    raise FileDownloadError(
+                        f"Failed to download {fi.filename}: {e}"
+                    )
+        return batch
+
+
+class AsyncFileOperations:
+    """Async file operations for a resource."""
+
+    def __init__(self, http: "AsyncHTTPClient", base_path: str) -> None:
+        self._http = http
+        self._base_path = base_path
+
+    async def list_files(
+        self,
+        resource_id: str,
+        subdir: Optional[str] = None,
+        response_model: type = None,  # type: ignore[assignment]
+    ) -> object:
+        """List files for a resource.
+
+        Args:
+            resource_id: The resource identifier.
+            subdir: Optional subdirectory filter.
+            response_model: Pydantic model for response.
+
+        Returns:
+            Parsed response object.
+        """
+        params = {}
+        if subdir:
+            params["subdir"] = subdir
+        return await self._http.request(
+            "GET",
+            f"{self._base_path}/{resource_id}/files",
+            params=params if params else None,
+            response_model=response_model,
+        )
+
+    async def get_download_url(
+        self, resource_id: str, file_id: str
+    ) -> FileDownloadResponse:
+        """Get a signed download URL for a file.
+
+        Args:
+            resource_id: The resource identifier.
+            file_id: The file identifier.
+
+        Returns:
+            Download URL response with signed URL.
+        """
+        return await self._http.request(
+            "GET",
+            (f"{self._base_path}/{resource_id}" f"/files/{file_id}/download"),
+            response_model=FileDownloadResponse,
+        )
+
+    async def read_bytes(
+        self,
+        resource_id: str,
+        file_id: str,
+    ) -> bytes:
+        """Read a file's content into memory.
+
+        Async counterpart of FileOperations.read_bytes().
+
+        Args:
+            resource_id: The resource identifier.
+            file_id: The file identifier.
+
+        Returns:
+            File content as bytes.
+
+        Raises:
+            FileDownloadError: If download fails.
+        """
+        resp = await self.get_download_url(resource_id, file_id)
+        try:
+            async with httpx.AsyncClient() as client:
+                r = await client.request(
+                    method=resp.method,
+                    url=resp.download_url,
+                )
+                r.raise_for_status()
+                return r.content
+        except Exception as e:
+            raise FileDownloadError(f"Failed to read file: {e}")
+
+    async def download(
+        self,
+        resource_id: str,
+        file_id: str,
+        destination: Union[str, Path],
+    ) -> Path:
+        """Download a file to a local path.
+
+        Args:
+            resource_id: The resource identifier.
+            file_id: The file identifier.
+            destination: Local file path to write to.
+
+        Returns:
+            Path to the downloaded file.
+
+        Raises:
+            FileDownloadError: If download fails.
+        """
+        resp = await self.get_download_url(resource_id, file_id)
+        destination = Path(destination)
+        await anyio.Path(destination.parent).mkdir(parents=True, exist_ok=True)
+        try:
+            async with httpx.AsyncClient() as client:
+                r = await client.request(
+                    method=resp.method,
+                    url=resp.download_url,
+                )
+                r.raise_for_status()
+                async with await anyio.open_file(destination, "wb") as f:
+                    await f.write(r.content)
+            return destination
+        except Exception as e:
+            raise FileDownloadError(f"Failed to download file: {e}")
+
+    async def download_batch(
+        self,
+        resource_id: str,
+        destination_dir: Union[str, Path],
+        subdir: Optional[str] = None,
+    ) -> BatchDownloadResponse:
+        """Download all files for a resource.
+
+        Args:
+            resource_id: The resource identifier.
+            destination_dir: Local directory to write to.
+            subdir: Optional subdirectory filter.
+
+        Returns:
+            Batch download response metadata.
+
+        Raises:
+            FileDownloadError: If any download fails.
+        """
+        params = {}
+        if subdir:
+            params["subdir"] = subdir
+        batch: BatchDownloadResponse = await self._http.request(
+            "POST",
+            (f"{self._base_path}/{resource_id}" f"/downloads"),
+            params=params if params else None,
+            response_model=BatchDownloadResponse,
+        )
+        dest = Path(destination_dir)
+        await anyio.Path(dest).mkdir(parents=True, exist_ok=True)
+
+        async def _download_one(
+            client: httpx.AsyncClient,
+            fi: BatchDownloadFile,
+        ) -> None:
+            try:
+                r = await client.request(
+                    method=fi.method,
+                    url=fi.download_url,
+                )
+                r.raise_for_status()
+                fp = (dest / fi.filename).resolve()
+                if not str(fp).startswith(str(dest.resolve())):
+                    raise FileDownloadError(
+                        f"Unsafe filename rejected: " f"{fi.filename}"
+                    )
+                async with await anyio.open_file(fp, "wb") as f:
+                    await f.write(r.content)
+            except FileDownloadError:
+                raise
+            except Exception as e:
+                raise FileDownloadError(
+                    f"Failed to download {fi.filename}: {e}"
+                )
+
+        async with httpx.AsyncClient() as client:
+            await asyncio.gather(
+                *[_download_one(client, fi) for fi in batch.files]
+            )
+        return batch

waveium/resources/_share_ops.py

@@ -0,0 +1,175 @@
+"""Reusable share operation mixins for resources."""
+
+from typing import TYPE_CHECKING
+
+from ..models.common import MessageResponse, PermissionLevel, ShareTargetType
+from ..models.shares import (
+    CreateShareRequest,
+    PaginatedShareResponse,
+    ShareResponse,
+)
+
+if TYPE_CHECKING:
+    from .._http import AsyncHTTPClient, HTTPClient
+
+
+class ShareOperations:
+    """Sync share operations for a resource."""
+
+    def __init__(self, http: "HTTPClient", base_path: str) -> None:
+        self._http = http
+        self._base_path = base_path
+
+    def create_share(
+        self,
+        resource_id: str,
+        shared_with_type: ShareTargetType,
+        shared_with_id: str,
+        permission_level: PermissionLevel,
+    ) -> ShareResponse:
+        """Create a share for a resource.
+
+        Args:
+            resource_id: The resource identifier.
+            shared_with_type: Target type (user/team/org).
+            shared_with_id: Target entity identifier.
+            permission_level: Permission (view/use/full).
+
+        Returns:
+            The created share record.
+        """
+        request = CreateShareRequest(
+            shared_with_type=shared_with_type,
+            shared_with_id=shared_with_id,
+            permission_level=permission_level,
+        )
+        return self._http.request(
+            "POST",
+            f"{self._base_path}/{resource_id}/shares",
+            json_data=request.model_dump(),
+            response_model=ShareResponse,
+        )
+
+    def list_shares(
+        self,
+        resource_id: str,
+        limit: int = 50,
+        offset: int = 0,
+    ) -> PaginatedShareResponse:
+        """List shares for a resource.
+
+        Args:
+            resource_id: The resource identifier.
+            limit: Maximum number of results.
+            offset: Number of results to skip.
+
+        Returns:
+            Paginated list of share records.
+        """
+        return self._http.request(
+            "GET",
+            f"{self._base_path}/{resource_id}/shares",
+            params={"limit": limit, "offset": offset},
+            response_model=PaginatedShareResponse,
+        )
+
+    def revoke_share(
+        self,
+        resource_id: str,
+        share_id: str,
+    ) -> MessageResponse:
+        """Revoke a share for a resource.
+
+        Args:
+            resource_id: The resource identifier.
+            share_id: The share identifier to revoke.
+
+        Returns:
+            Confirmation message response.
+        """
+        return self._http.request(
+            "DELETE",
+            (f"{self._base_path}/{resource_id}" f"/shares/{share_id}"),
+            response_model=MessageResponse,
+        )
+
+
+class AsyncShareOperations:
+    """Async share operations for a resource."""
+
+    def __init__(self, http: "AsyncHTTPClient", base_path: str) -> None:
+        self._http = http
+        self._base_path = base_path
+
+    async def create_share(
+        self,
+        resource_id: str,
+        shared_with_type: ShareTargetType,
+        shared_with_id: str,
+        permission_level: PermissionLevel,
+    ) -> ShareResponse:
+        """Create a share for a resource.
+
+        Args:
+            resource_id: The resource identifier.
+            shared_with_type: Target type (user/team/org).
+            shared_with_id: Target entity identifier.
+            permission_level: Permission (view/use/full).
+
+        Returns:
+            The created share record.
+        """
+        request = CreateShareRequest(
+            shared_with_type=shared_with_type,
+            shared_with_id=shared_with_id,
+            permission_level=permission_level,
+        )
+        return await self._http.request(
+            "POST",
+            f"{self._base_path}/{resource_id}/shares",
+            json_data=request.model_dump(),
+            response_model=ShareResponse,
+        )
+
+    async def list_shares(
+        self,
+        resource_id: str,
+        limit: int = 50,
+        offset: int = 0,
+    ) -> PaginatedShareResponse:
+        """List shares for a resource.
+
+        Args:
+            resource_id: The resource identifier.
+            limit: Maximum number of results.
+            offset: Number of results to skip.
+
+        Returns:
+            Paginated list of share records.
+        """
+        return await self._http.request(
+            "GET",
+            f"{self._base_path}/{resource_id}/shares",
+            params={"limit": limit, "offset": offset},
+            response_model=PaginatedShareResponse,
+        )
+
+    async def revoke_share(
+        self,
+        resource_id: str,
+        share_id: str,
+    ) -> MessageResponse:
+        """Revoke a share for a resource.
+
+        Args:
+            resource_id: The resource identifier.
+            share_id: The share identifier to revoke.
+
+        Returns:
+            Confirmation message response.
+        """
+        return await self._http.request(
+            "DELETE",
+            (f"{self._base_path}/{resource_id}" f"/shares/{share_id}"),
+            response_model=MessageResponse,
+        )