dominus-sdk-python-dev 2.1.8__py3-none-any.whl → 2.2.0__py3-none-any.whl

dominus/namespaces/db.py

@@ -45,6 +45,24 @@ class DbNamespace:
     def __init__(self, client: "Dominus"):
         self._client = client
 
+    async def schemas(self) -> List[str]:
+        """
+        List accessible schemas.
+
+        Returns schemas that the current user can access (public, tenant_*, etc.)
+        Excludes system schemas (auth, logs, meta, object, etc.)
+
+        Returns:
+            List of schema names
+        """
+        result = await self._client._request(
+            endpoint="/api/scribe/schema/list",
+            method="GET"
+        )
+        if isinstance(result, list):
+            return result
+        return result.get("schemas", [])
+
     async def tables(self, schema: str = "public") -> List[Dict[str, Any]]:
         """
         List tables in a schema.
@@ -123,11 +141,18 @@ class DbNamespace:
         if actor:
             body["actor"] = actor
 
-        return await self._client._request(
+        # Backend returns {items, total, limit, offset} but we normalize to {rows, total}
+        result = await self._client._request(
             endpoint=f"/api/scribe/data/{schema}/{table}/query",
             body=body
         )
 
+        # Normalize response - map 'items' to 'rows' for consistent interface
+        return {
+            "rows": result.get("items", result.get("rows", [])),
+            "total": result.get("total", 0)
+        }
+
     async def insert(
         self,
         table: str,

dominus/namespaces/ddl.py

@@ -588,3 +588,209 @@ class DdlNamespace:
             endpoint=f"/api/smith/provision/tenants-by-category/{category_slug}",
             method="GET"
         )
+
+    # ========================================
+    # SCHEMA BUILDER (UI SUPPORT)
+    # ========================================
+
+    async def get_category_structure(self, category_slug: str) -> Dict[str, Any]:
+        """
+        Get schema structure for a category (for Schema Builder UI).
+
+        Returns tables, columns, indexes, constraints for all tables.
+
+        Returns:
+            Dict with category, tenant_count, tables, current_version, migration_count
+        """
+        return await self._client._request(
+            endpoint=f"/api/smith/builder/category/{category_slug}/structure",
+            method="GET"
+        )
+
+    async def get_category_migration_history(self, category_slug: str) -> Dict[str, Any]:
+        """
+        Get migration history for a category.
+
+        Returns:
+            Dict with migrations, stored_versions, current_version, total
+        """
+        return await self._client._request(
+            endpoint=f"/api/smith/builder/category/{category_slug}/migrations",
+            method="GET"
+        )
+
+    async def preview_migration(
+        self,
+        category_slug: str,
+        operation: str,
+        params: Dict[str, Any],
+        migration_name: str
+    ) -> Dict[str, Any]:
+        """
+        Preview a migration before applying.
+
+        Args:
+            category_slug: Category identifier
+            operation: Operation type (create_table, add_column, etc.)
+            params: Operation parameters
+            migration_name: Human-readable migration name
+
+        Returns:
+            Dict with affected_tenants, migration_preview, sql_preview
+        """
+        return await self._client._request(
+            endpoint=f"/api/smith/builder/category/{category_slug}/preview-migration",
+            body={
+                "operation": operation,
+                "params": params,
+                "migration_name": migration_name
+            }
+        )
+
+    async def apply_builder_migration(
+        self,
+        category_slug: str,
+        operation: str,
+        params: Dict[str, Any],
+        migration_name: str
+    ) -> Dict[str, Any]:
+        """
+        Apply a migration from Schema Builder.
+
+        Args:
+            category_slug: Category identifier
+            operation: Operation type (create_table, add_column, etc.)
+            params: Operation parameters
+            migration_name: Human-readable migration name
+
+        Returns:
+            Dict with success, migration_id, b2_key, applied_schemas, tenant_count, versions_recorded
+        """
+        return await self._client._request(
+            endpoint=f"/api/smith/builder/category/{category_slug}/apply-migration",
+            body={
+                "operation": operation,
+                "params": params,
+                "migration_name": migration_name
+            },
+            timeout=120000  # 2 minutes for migration operations
+        )
+
+    async def get_builder_migration_file(
+        self,
+        category_slug: str,
+        version_id: str
+    ) -> Dict[str, Any]:
+        """
+        Get a specific migration file content from B2 storage.
+
+        Args:
+            category_slug: Category identifier
+            version_id: Migration version ID
+
+        Returns:
+            Dict with version_id, content, migration_name, b2_key
+        """
+        return await self._client._request(
+            endpoint=f"/api/smith/builder/category/{category_slug}/migrations/{version_id}",
+            method="GET"
+        )
+
+    async def get_tenant_sync_status(self, category_slug: str) -> Dict[str, Any]:
+        """
+        Get sync status for all tenants in a category.
+
+        Shows which tenants are on which migration version.
+
+        Returns:
+            Dict with category_slug, latest_version, total_tenants, synced_count,
+            pending_count, tenants
+        """
+        return await self._client._request(
+            endpoint=f"/api/smith/builder/category/{category_slug}/sync-status",
+            method="GET"
+        )
+
+    async def sync_tenants_to_latest(self, category_slug: str) -> Dict[str, Any]:
+        """
+        Sync all tenants in a category to the latest migration version.
+
+        Applies any pending migrations to tenants that are behind.
+
+        Returns:
+            Dict with success, message, synced_count, failed_count, results
+        """
+        return await self._client._request(
+            endpoint=f"/api/smith/builder/category/{category_slug}/sync-tenants",
+            method="POST",
+            timeout=120000  # 2 minutes for sync operations
+        )
+
+    # ========================================
+    # RESET / DELETE OPERATIONS
+    # ========================================
+
+    async def reset_category_schema(self, category_slug: str) -> Dict[str, Any]:
+        """
+        Factory reset a category's schema.
+
+        WARNING: This is a destructive operation that:
+        - Drops ALL tenant schemas in this category (CASCADE)
+        - Clears ALL migration history from meta.alembic_version
+        - Recreates empty schemas for each tenant
+        - Deletes ALL migration files from B2 storage
+
+        After reset, the category is back to a blank slate.
+
+        Returns:
+            Dict with success, message, reset_count, failed_count, migrations_deleted, results
+        """
+        return await self._client._request(
+            endpoint=f"/api/smith/builder/category/{category_slug}/reset",
+            method="DELETE",
+            timeout=120000  # 2 minutes for reset operations
+        )
+
+    async def reset_tenant_schema(
+        self,
+        category_slug: str,
+        tenant_slug: str
+    ) -> Dict[str, Any]:
+        """
+        Reset a single tenant's schema to blank.
+
+        WARNING: This is a destructive operation that:
+        - Clears the tenant's migration history from meta.alembic_version
+        - Drops the tenant's schema with CASCADE
+        - Recreates an empty schema
+
+        The tenant can then re-sync to apply current category migrations.
+
+        Returns:
+            Dict with success, message, tenant_slug, schema, versions_cleared
+        """
+        return await self._client._request(
+            endpoint=f"/api/smith/builder/category/{category_slug}/tenants/{tenant_slug}/reset",
+            method="DELETE",
+            timeout=60000  # 1 minute for single tenant reset
+        )
+
+    async def delete_migration(
+        self,
+        category_slug: str,
+        version_id: str
+    ) -> Dict[str, Any]:
+        """
+        Delete a single migration file from B2 storage.
+
+        WARNING: This does NOT clean up meta.alembic_version records.
+        Tenants that have already applied this migration keep their history.
+        Use with caution - typically only for cleaning up test migrations.
+
+        Returns:
+            Dict with success, message, version_id, category_slug
+        """
+        return await self._client._request(
+            endpoint=f"/api/smith/builder/category/{category_slug}/migrations/{version_id}",
+            method="DELETE"
+        )

dominus/namespaces/fastapi.py

@@ -0,0 +1,252 @@
+"""
+FastAPI Namespace - Decorators for route authentication.
+
+Provides decorator-style auth for FastAPI routes:
+
+    from dominus import dominus
+
+    @router.get("/protected")
+    @dominus.fastapi.jwt
+    async def route(claims: dict):
+        # claims contains JWT payload
+        ...
+
+    @router.get("/scoped")
+    @dominus.fastapi.scopes(["api:read", "data:read"])
+    async def route(claims: dict):
+        # claims validated to have at least one scope
+        ...
+
+    @router.get("/psk-protected")
+    @dominus.fastapi.psk
+    async def route(client: dict):
+        # client contains {id, name, tenant_id, scopes, roles, status}
+        ...
+
+Parameter naming conventions:
+- @jwt and @scopes: function must have a 'claims' parameter
+- @psk: function must have a 'client' parameter
+"""
+from functools import wraps
+from typing import Any, Callable, Dict, List, Optional, TYPE_CHECKING
+import inspect
+
+if TYPE_CHECKING:
+    from ..start import Dominus
+
+
+class FastAPINamespace:
+    """
+    FastAPI authentication decorators namespace.
+
+    Usage:
+        from dominus import dominus
+
+        @router.get("/protected")
+        @dominus.fastapi.jwt
+        async def my_route(claims: dict):
+            return {"user": claims.get("sub")}
+    """
+
+    def __init__(self, client: "Dominus"):
+        self._client = client
+
+    def jwt(self, func: Callable) -> Callable:
+        """
+        Decorator: Require valid JWT in Authorization header.
+
+        Injects JWT claims into the 'claims' parameter.
+
+        Usage:
+            @router.get("/protected")
+            @dominus.fastapi.jwt
+            async def route(claims: dict):
+                return {"user": claims.get("sub")}
+
+        Raises:
+            HTTPException 401: Missing/invalid Authorization header or token
+        """
+        return self._create_auth_decorator(func, auth_type="jwt")
+
+    def psk(self, func: Callable) -> Callable:
+        """
+        Decorator: Require valid PSK in Authorization: Bearer header.
+
+        Injects client info into the 'client' parameter.
+
+        Usage:
+            @router.get("/protected")
+            @dominus.fastapi.psk
+            async def route(client: dict):
+                return {"client_name": client.get("name")}
+
+        Raises:
+            HTTPException 401: Missing/invalid Authorization header or PSK
+        """
+        return self._create_auth_decorator(func, auth_type="psk")
+
+    def scopes(self, allowed_scopes: List[str]) -> Callable:
+        """
+        Decorator factory: Require JWT with specific scopes.
+
+        Access granted if client has ANY of the allowed scopes.
+        Injects JWT claims into the 'claims' parameter.
+
+        Usage:
+            @router.get("/admin")
+            @dominus.fastapi.scopes(["admin:read", "admin:write"])
+            async def route(claims: dict):
+                return {"admin": True}
+
+        Args:
+            allowed_scopes: List of scope strings, any one grants access
+
+        Raises:
+            HTTPException 401: Missing/invalid Authorization header or token
+            HTTPException 403: Token valid but missing required scopes
+        """
+        def decorator(func: Callable) -> Callable:
+            return self._create_auth_decorator(func, auth_type="jwt", required_scopes=allowed_scopes)
+        return decorator
+
+    def _create_auth_decorator(
+        self,
+        func: Callable,
+        auth_type: str,
+        required_scopes: Optional[List[str]] = None
+    ) -> Callable:
+        """
+        Internal: Create an auth decorator for the given function.
+
+        Args:
+            func: The route function to wrap
+            auth_type: "jwt" or "psk"
+            required_scopes: Optional list of scopes to require (jwt only)
+        """
+        # Import here to avoid circular imports and make fastapi optional
+        from fastapi import Header, HTTPException
+
+        # Determine the parameter name to inject
+        param_name = "claims" if auth_type == "jwt" else "client"
+
+        # Validate the function has the required parameter
+        sig = inspect.signature(func)
+        if param_name not in sig.parameters:
+            raise ValueError(
+                f"@dominus.fastapi.{auth_type} requires a '{param_name}' parameter. "
+                f"Add '{param_name}: dict' to your function signature."
+            )
+
+        @wraps(func)
+        async def wrapper(*args, **kwargs):
+            # Get Authorization header from the request
+            # FastAPI injects this via the wrapper's signature
+            authorization = kwargs.pop("_dominus_authorization", None)
+
+            if not authorization:
+                raise HTTPException(
+                    status_code=401,
+                    detail="Missing Authorization header",
+                    headers={"WWW-Authenticate": "Bearer"}
+                )
+
+            # Extract Bearer token
+            token = self._extract_bearer(authorization)
+            if not token:
+                raise HTTPException(
+                    status_code=401,
+                    detail="Invalid Authorization header format. Expected: Bearer <token>",
+                    headers={"WWW-Authenticate": "Bearer"}
+                )
+
+            # Validate based on auth type
+            if auth_type == "jwt":
+                auth_data = await self._validate_jwt(token)
+                if not auth_data:
+                    raise HTTPException(
+                        status_code=401,
+                        detail="Invalid or expired token",
+                        headers={"WWW-Authenticate": "Bearer"}
+                    )
+
+                # Check scopes if required
+                if required_scopes:
+                    client_scopes = auth_data.get("scopes", [])
+                    if not any(scope in client_scopes for scope in required_scopes):
+                        raise HTTPException(
+                            status_code=403,
+                            detail=f"Missing required scope. Need one of: {required_scopes}"
+                        )
+            else:  # psk
+                auth_data = await self._validate_psk(token)
+                if not auth_data:
+                    raise HTTPException(
+                        status_code=401,
+                        detail="Invalid API key",
+                        headers={"WWW-Authenticate": "Bearer"}
+                    )
+
+            # Inject the auth data into the function
+            kwargs[param_name] = auth_data
+
+            # Call the original function
+            return await func(*args, **kwargs)
+
+        # Modify the wrapper signature to include Authorization header
+        # This allows FastAPI to inject it automatically
+        old_sig = inspect.signature(func)
+        old_params = list(old_sig.parameters.values())
+
+        # Remove the claims/client param (we'll inject it manually)
+        new_params = [p for p in old_params if p.name != param_name]
+
+        # Add the Authorization header param
+        auth_param = inspect.Parameter(
+            "_dominus_authorization",
+            inspect.Parameter.KEYWORD_ONLY,
+            default=Header(None, alias="Authorization"),
+            annotation=Optional[str]
+        )
+        new_params.append(auth_param)
+
+        # Create new signature
+        wrapper.__signature__ = old_sig.replace(parameters=new_params)
+
+        return wrapper
+
+    def _extract_bearer(self, auth_header: str) -> Optional[str]:
+        """Extract token from Authorization: Bearer <token> header."""
+        if not auth_header or not auth_header.startswith("Bearer "):
+            return None
+        return auth_header[7:]
+
+    async def _validate_jwt(self, token: str) -> Optional[Dict[str, Any]]:
+        """Validate JWT and return claims."""
+        try:
+            return await self._client.validate_jwt(token)
+        except (ValueError, Exception):
+            return None
+
+    async def _validate_psk(self, psk: str) -> Optional[Dict[str, Any]]:
+        """
+        Validate PSK and return client info with scopes/roles.
+
+        Uses portal.login_client to exchange PSK for JWT, then decodes
+        the JWT to get the client's claims (scopes, roles, tenants, etc.).
+        """
+        try:
+            # Exchange PSK for JWT via portal.login_client
+            # This uses the SDK's project JWT + the subsidiary client's PSK
+            result = await self._client.portal.login_client(psk=psk)
+            if not result:
+                return None
+
+            jwt = result.get("access_token")
+            if not jwt:
+                return None
+
+            # Decode JWT to get claims (includes scopes, roles, tenants, etc.)
+            claims = await self._client.validate_jwt(jwt)
+            return claims
+        except Exception:
+            return None

dominus/namespaces/files.py

@@ -297,3 +297,183 @@ class FilesNamespace:
             endpoint="/api/archivist/update",
             body=body
         )
+
+    # ========================================
+    # STORAGE BROWSER METHODS
+    # ========================================
+
+    async def browse(
+        self,
+        path: str = "/",
+        category: Optional[str] = None,
+        view: Optional[str] = None,
+        limit: int = 100,
+        cursor: Optional[str] = None
+    ) -> Dict[str, Any]:
+        """
+        Browse files and folders at a path.
+
+        Args:
+            path: Directory path to browse (default: "/")
+            category: Filter by category
+            view: View name (e.g., "all", "compliance")
+            limit: Maximum items to return (default: 100)
+            cursor: Pagination cursor
+
+        Returns:
+            Dict with "path", "folders", "files", and optional "cursor"
+        """
+        body = {
+            "path": path,
+            "limit": limit
+        }
+
+        if category:
+            body["category"] = category
+        if view:
+            body["view"] = view
+        if cursor:
+            body["cursor"] = cursor
+
+        return await self._client._request(
+            endpoint="/api/archivist/browse",
+            body=body
+        )
+
+    async def get_storage_stats(self) -> Dict[str, Any]:
+        """
+        Get storage statistics.
+
+        Returns:
+            Dict with "total_objects", "total_size_bytes", "by_category"
+        """
+        return await self._client._request(
+            endpoint="/api/archivist/stats",
+            method="GET"
+        )
+
+    async def list_categories(self) -> Dict[str, Any]:
+        """
+        List all file categories.
+
+        Returns:
+            Dict with "categories" list containing name, object_count, total_size_bytes
+        """
+        return await self._client._request(
+            endpoint="/api/archivist/categories",
+            method="GET"
+        )
+
+    async def list_views(self, include_reserved: bool = False) -> Dict[str, Any]:
+        """
+        List available views.
+
+        Args:
+            include_reserved: Include reserved system views (default: False)
+
+        Returns:
+            Dict with "views" list, "total_views", "is_admin"
+        """
+        body = {"include_reserved": include_reserved}
+
+        return await self._client._request(
+            endpoint="/api/archivist/views",
+            body=body
+        )
+
+    async def list_categories_in_view(self, view: str) -> Dict[str, Any]:
+        """
+        List categories within a specific view.
+
+        Args:
+            view: View name
+
+        Returns:
+            Dict with "categories" list
+        """
+        return await self._client._request(
+            endpoint=f"/api/archivist/views/{view}/categories",
+            method="GET"
+        )
+
+    async def create_folder(
+        self,
+        path: str,
+        category: Optional[str] = None
+    ) -> Dict[str, Any]:
+        """
+        Create a folder.
+
+        Args:
+            path: Folder path to create
+            category: Category for the folder (optional)
+
+        Returns:
+            Dict with "created", "path", optional "placeholder_id", "message"
+        """
+        body = {"path": path}
+
+        if category:
+            body["category"] = category
+
+        return await self._client._request(
+            endpoint="/api/archivist/folder/create",
+            body=body
+        )
+
+    async def delete_folder(
+        self,
+        path: str,
+        category: Optional[str] = None,
+        force: bool = False
+    ) -> Dict[str, Any]:
+        """
+        Delete a folder.
+
+        Args:
+            path: Folder path to delete
+            category: Category of the folder (optional)
+            force: Force delete non-empty folders (default: False)
+
+        Returns:
+            Dict with "deleted", "path", "deleted_count", etc.
+        """
+        body = {
+            "path": path,
+            "force": force
+        }
+
+        if category:
+            body["category"] = category
+
+        return await self._client._request(
+            endpoint="/api/archivist/folder/delete",
+            body=body
+        )
+
+    async def factory_reset(
+        self,
+        confirm: bool = False,
+        preserve_compliance: bool = True
+    ) -> Dict[str, Any]:
+        """
+        Factory reset storage (delete all non-compliance files).
+
+        WARNING: This is a destructive operation.
+
+        Args:
+            confirm: Must be True to proceed (safety check)
+            preserve_compliance: Keep compliance files (default: True)
+
+        Returns:
+            Dict with "reset", "deleted_count", "retained_count", "by_category"
+        """
+        body = {
+            "confirm": confirm,
+            "preserve_compliance": preserve_compliance
+        }
+
+        return await self._client._request(
+            endpoint="/api/archivist/factory-reset",
+            body=body
+        )