@ngocsangairvds/vsaf 3.1.27 → 3.2.1

package/tools/vds-scripts/confluence_orchestrator/src/confluence_orchestrator/http.py

@@ -0,0 +1,1114 @@
+"""Confluence client wrapper using atlassian-python-api for consistency."""
+
+from __future__ import annotations
+
+import inspect
+import time
+from dataclasses import dataclass
+from typing import Any
+
+import httpx
+import structlog
+
+try:  # Prefer new-style Atlassian clients when available
+    from atlassian.confluence import ConfluenceCloud as AtlassianConfluenceCloud
+    from atlassian.confluence import ConfluenceServer as AtlassianConfluenceServer
+except ImportError:  # Fall back to legacy class
+    from atlassian import Confluence as AtlassianConfluenceCloud  # type: ignore
+    AtlassianConfluenceServer = AtlassianConfluenceCloud
+
+from .config import ConfluenceSettings
+from .errors import (
+    ConfluenceAuthError,
+    ConfluenceClientError,
+    ConfluenceConflictError,
+    ConfluencePermissionError,
+    ConfluenceRateLimitedError,
+    ConfluenceResponseError,
+    ConfluenceTransportError,
+)
+
+
+@dataclass(slots=True)
+class RetryConfig:
+    max_attempts: int = 3
+    backoff_factor: float = 0.5
+    max_wait: float = 5.0
+
+
+class ConfluenceHttpClient:
+    def __init__(
+        self,
+        settings: ConfluenceSettings,
+        *,
+        server: str = "internal",
+        client: httpx.Client | None = None,
+        retry_config: RetryConfig | None = None,
+    ) -> None:
+        token = settings.token_for(server)
+        if not token:
+            raise ConfluenceAuthError(
+                f"Token for server '{server}' is missing.",
+                context={"server": server},
+            )
+
+        self._settings = settings
+        self._server = server
+        self._token = token
+        self._retry = retry_config or RetryConfig()
+        if client is None:
+            base_url = str(settings.url_for(server))
+            client = httpx.Client(
+                base_url=base_url,
+                headers={
+                    "Authorization": f"Bearer {token}",
+                    "Accept": "application/json",
+                },
+                timeout=30,
+            )
+        self._client = client
+
+    def close(self) -> None:
+        self._client.close()
+
+    def __enter__(self) -> ConfluenceHttpClient:
+        return self
+
+    def __exit__(self, exc_type, exc, tb) -> None:  # type: ignore[override]
+        self.close()
+
+    def request(self, method: str, path: str, **kwargs: Any) -> httpx.Response:
+        attempt = 0
+        while True:
+            try:
+                response = self._client.request(method, path, **kwargs)
+            except httpx.HTTPError as exc:  # pragma: no cover - network errors
+                raise ConfluenceTransportError(f"HTTP transport error: {exc}") from exc
+
+            if response.status_code < 400:
+                return response
+
+            if response.status_code in {401, 403}:
+                raise ConfluenceAuthError(
+                    "Authentication failed",
+                    context={"status_code": response.status_code},
+                )
+            if response.status_code == 409:
+                raise ConfluenceConflictError(
+                    "Request conflicted with existing state",
+                    context={"status_code": response.status_code},
+                )
+
+            should_retry = response.status_code in {429, 500, 502, 503, 504}
+            if should_retry and attempt < self._retry.max_attempts - 1:
+                retry_after = response.headers.get("Retry-After")
+                if retry_after:
+                    try:
+                        wait = min(float(retry_after), self._retry.max_wait)
+                    except ValueError:
+                        wait = self._retry.backoff_factor * (2**attempt)
+                else:
+                    wait = self._retry.backoff_factor * (2**attempt)
+                wait = min(wait, self._retry.max_wait)
+                time.sleep(wait)
+                attempt += 1
+                continue
+
+            raise ConfluenceResponseError(
+                f"Unexpected status {response.status_code}",
+                status_code=response.status_code,
+                context={"status_code": response.status_code, "body": response.text[:256]},
+            )
+
+
+class ConfluenceClient:
+    """Confluence client wrapper using atlassian-python-api SDK."""
+
+    def __init__(
+        self,
+        settings: ConfluenceSettings,
+        *,
+        server: str | None = None,
+        timeout: int | None = 30,
+    ) -> None:
+        self._settings = settings
+        self._server = server or settings.default_server
+        self._timeout = timeout or 30
+
+        base_url = str(settings.url_for(self._server))
+        token = settings.token_for(self._server)
+
+        # Decide whether this endpoint should be treated as Cloud (v2) or Server (v1)
+        self._is_cloud = self._looks_like_cloud(base_url)
+        client_cls = AtlassianConfluenceCloud if self._is_cloud else AtlassianConfluenceServer
+
+        # Configure authentication based on available credentials
+        auth_kwargs: dict[str, Any] = {"url": base_url, "timeout": self._timeout}
+        if self._is_cloud:
+            if not token:
+                raise ConfluenceAuthError(
+                    f"No API token available for cloud server '{self._server}'.",
+                    context={"server": self._server},
+                )
+            auth_kwargs["token"] = token
+        else:
+            if settings.username and settings.password:
+                auth_kwargs["username"] = settings.username
+                auth_kwargs["password"] = settings.password
+            elif token:
+                # Recent ConfluenceServer class also supports PATs
+                auth_kwargs["token"] = token
+            else:
+                raise ConfluenceAuthError(
+                    f"No credentials available for server '{self._server}'. "
+                    "Provide VDS_USERNAME+VDS_PASSWORD or a CONFLUENCE token.",
+                    context={"server": self._server},
+                )
+
+        try:
+            self._client = client_cls(**auth_kwargs)
+        except Exception as exc:
+            raise ConfluenceTransportError(
+                f"Failed to initialize Confluence client: {exc}", context={"server": self._server, "base_url": base_url}
+            ) from exc
+
+        self._log = structlog.get_logger(__name__).bind(server=self._server, base_url=base_url)
+
+        # Store retry settings
+        self._max_retries = settings.max_retries
+        self._retry_backoff_factor = settings.retry_backoff_factor
+        self._create_params = set(self._safe_signature_params(self._client.create_page))
+        self._update_params = set(self._safe_signature_params(self._client.update_page))
+
+    def supports_api_version(self, version: str) -> bool:
+        version = (version or "v1").lower()
+        if version == "v1":
+            return True
+        if version == "v2":
+            return self._is_cloud
+        return False
+
+    @staticmethod
+    def _looks_like_cloud(base_url: str) -> bool:
+        lowered = base_url.lower()
+        return any(indicator in lowered for indicator in ("atlassian.net", "atlassian.com"))
+
+    @staticmethod
+    def _safe_signature_params(method) -> list[str]:
+        try:
+            return list(inspect.signature(method).parameters.keys())
+        except (TypeError, ValueError):
+            return []
+
+    def _handle_api_error(self, error: Exception, operation: str) -> None:
+        """Convert atlassian-python-api errors to our standardized errors."""
+        error_str = str(error).lower()
+
+        if "unauthorized" in error_str or "authentication" in error_str or "401" in error_str:
+            raise ConfluenceAuthError(f"Authentication failed during {operation}", context={"error": str(error)})
+        elif "forbidden" in error_str or "403" in error_str:
+            raise ConfluenceAuthError(f"Access forbidden during {operation}", context={"error": str(error)})
+        elif "rate limit" in error_str or "429" in error_str:
+            raise ConfluenceRateLimitedError(f"Rate limited during {operation}", context={"error": str(error)})
+        elif "conflict" in error_str or "409" in error_str:
+            raise ConfluenceConflictError(f"Conflict during {operation}", context={"error": str(error)})
+        elif "server error" in error_str or "500" in error_str:
+            raise ConfluenceResponseError(f"Server error during {operation}", context={"error": str(error)})
+        else:
+            raise ConfluenceClientError(f"API error during {operation}: {error}", context={"error": str(error)})
+
+    def _with_retry(self, operation, operation_name: str):
+        """Execute an operation with retry logic using instance settings."""
+        for attempt in range(self._max_retries + 1):
+            try:
+                result = operation()
+                return result
+            except Exception as exc:
+                try:
+                    self._handle_api_error(exc, operation_name)
+                except (ConfluenceTransportError, ConfluenceRateLimitedError) as retry_exc:
+                    if attempt == self._max_retries:
+                        self._log.error(
+                            "retry_attempts_exhausted",
+                            operation=operation_name,
+                            attempts=self._max_retries,
+                            final_error=str(retry_exc),
+                        )
+                        from .errors import ConfluenceRetryError
+
+                        raise ConfluenceRetryError(
+                            f"Retry attempts exhausted: {retry_exc}",
+                            attempts=self._max_retries,
+                            context={"original_error": str(retry_exc), "operation": operation_name},
+                        ) from retry_exc
+
+                    wait_time = self._retry_backoff_factor * (2**attempt)
+                    self._log.warning(
+                        "retry_attempt",
+                        operation=operation_name,
+                        attempt=attempt + 1,
+                        max_retries=self._max_retries,
+                        wait_time=wait_time,
+                        error=str(retry_exc),
+                    )
+                    time.sleep(wait_time)
+                except ConfluenceClientError:
+                    # Don't retry on client errors (auth, not found, etc.)
+                    raise
+
+    def get_page(self, page_id: str, expand: list[str] | None = None) -> dict[str, Any]:
+        """Get a page by ID."""
+
+        def operation():
+            params = {}
+            if expand:
+                params["expand"] = ",".join(expand)
+            result = self._client.get_page_by_id(page_id, expand=",".join(expand) if expand else None)
+            self._log.debug("page_retrieved", page_id=page_id)
+            return result
+
+        return self._with_retry(operation, f"get_page {page_id}")
+
+    def search_cql(
+        self, cql: str, limit: int = 25, expand: list[str] | None = None, **kwargs: Any
+    ) -> dict[str, Any]:
+        """Search using CQL."""
+
+        def operation():
+            result = self._client.cql(cql, limit=limit, expand=",".join(expand) if expand else None, **kwargs)
+            self._log.debug("cql_search_completed", cql=cql, limit=limit)
+            return result
+
+        return self._with_retry(operation, f"cql_search {cql}")
+
+    def cql_advanced(
+        self,
+        cql: str,
+        *,
+        limit: int = 25,
+        start: int = 0,
+        expand: list[str] | None = None,
+        excerpt: str | None = None,
+        **kwargs: Any,
+    ) -> dict[str, Any]:
+        """Advanced CQL search with additional options.
+
+        Args:
+            cql: CQL query string
+            limit: Maximum number of results (default: 25)
+            start: Start index for pagination (default: 0)
+            expand: Optional list of fields to expand
+            excerpt: Optional excerpt strategy (e.g., "highlighted", "indexed")
+            **kwargs: Additional options passed to SDK cql() method
+        """
+
+        def operation():
+            expand_str = ",".join(expand) if expand else None
+            # SDK cql() method supports start parameter via kwargs
+            cql_kwargs = {"limit": limit, "start": start, **kwargs}
+            if expand_str:
+                cql_kwargs["expand"] = expand_str
+            if excerpt:
+                cql_kwargs["excerpt"] = excerpt
+
+            result = self._client.cql(cql, **cql_kwargs)  # type: ignore[call-arg]
+            self._log.debug("cql_advanced_search_completed", cql=cql, limit=limit, start=start)
+            return result
+
+        return self._with_retry(operation, f"cql_advanced_search {cql}")
+
+    def search_by_space_and_type(
+        self,
+        space_key: str | None = None,
+        content_type: str | None = None,
+        *,
+        limit: int = 25,
+        start: int = 0,
+        expand: list[str] | None = None,
+        **kwargs: Any,
+    ) -> dict[str, Any]:
+        """Search by space and content type (helper method that builds CQL).
+
+        Args:
+            space_key: Optional space key to filter by
+            content_type: Optional content type (e.g., "page", "blogpost", "comment")
+            limit: Maximum number of results (default: 25)
+            start: Start index for pagination (default: 0)
+            expand: Optional list of fields to expand
+            **kwargs: Additional options passed to CQL search
+        """
+        # Build CQL query
+        cql_parts: list[str] = []
+        if space_key:
+            cql_parts.append(f'space = "{space_key}"')
+        if content_type:
+            cql_parts.append(f'type = "{content_type}"')
+
+        if not cql_parts:
+            raise ConfluenceClientError(
+                "At least one of space_key or content_type must be provided",
+                context={},
+            )
+
+        cql = " AND ".join(cql_parts)
+        return self.cql_advanced(cql, limit=limit, start=start, expand=expand, **kwargs)
+
+    def create_page(
+        self, space_key: str, title: str, body: str, parent_id: str | None = None, **kwargs: Any
+    ) -> dict[str, Any]:
+        """Create a new page."""
+
+        def operation():
+            call_kwargs: dict[str, Any] = {}
+            if parent_id is not None:
+                call_kwargs["parent_id"] = parent_id
+            for key, value in kwargs.items():
+                if key in self._create_params and value is not None:
+                    call_kwargs[key] = value
+            result = self._client.create_page(space=space_key, title=title, body=body, **call_kwargs)
+            self._log.info("page_created", space_key=space_key, title=title, page_id=result.get("id"))
+            return result
+
+        return self._with_retry(operation, f"create_page {title}")
+
+    def update_page(
+        self, page_id: str, title: str, body: str | None = None, version: int | None = None, **kwargs: Any
+    ) -> dict[str, Any]:
+        """Update an existing page."""
+
+        def operation():
+            call_kwargs: dict[str, Any] = {}
+            for key, value in kwargs.items():
+                if key in self._update_params and value is not None:
+                    call_kwargs[key] = value
+            if version is not None and "version" in self._update_params:
+                call_kwargs["version"] = version
+            result = self._client.update_page(page_id, title, body, **call_kwargs)
+            self._log.info("page_updated", page_id=page_id, title=title)
+            return result
+
+        return self._with_retry(operation, f"update_page {page_id}")
+
+    def delete_page(self, page_id: str) -> None:
+        """Delete a page."""
+        try:
+            # Use remove_page method from atlassian library
+            self._client.remove_page(page_id=page_id)
+            self._log.info("page_deleted", page_id=page_id)
+
+        except Exception as exc:
+            # Check if it's a permission issue
+            if "Unable to trash content" in str(exc) or "Unable to purge content" in str(exc):
+                self._log.warning("page_delete_permission_denied", page_id=page_id, error=str(exc))
+                raise ConfluencePermissionError(
+                    f"Permission denied when deleting page {page_id}. The page may be restricted or you may not have delete permissions.",
+                    context={"page_id": page_id, "original_error": str(exc)},
+                ) from exc
+            else:
+                self._handle_api_error(exc, f"delete_page {page_id}")
+
+    def request(self, method: str, path: str, **kwargs: Any) -> Any:
+        """Make a raw HTTP request using the atlassian client."""
+        try:
+            # Use the underlying request method from atlassian library
+            response = self._client.request(method=method, path=path, **kwargs)
+            self._log.debug("http_request", method=method, path=path)
+            return response
+
+        except Exception as exc:
+            self._handle_api_error(exc, f"request {method} {path}")
+
+    def add_attachment(
+        self,
+        page_id: str,
+        filename: str,
+        content: bytes,
+        content_type: str | None = None,
+        *,
+        comment: str | None = None,
+    ) -> dict[str, Any]:
+        """Add an attachment to a page.
+
+        According to atlassian-python-api docs, attach_content automatically updates
+        if the file exists, versioning the new file and keeping the old one.
+        See: https://atlassian-python-api.readthedocs.io/confluence.html#
+        """
+
+        def operation():
+            # Use attach_content from the official SDK (handles create vs update internally)
+            result = self._client.attach_content(
+                content=content,
+                name=filename,
+                content_type=content_type or "application/octet-stream",
+                page_id=page_id,
+                comment=comment,
+            )
+            self._log.info("attachment_added", page_id=page_id, filename=filename)
+            return result
+
+        return self._with_retry(operation, f"add_attachment {filename}")
+
+    def get_space(self, space_key: str) -> dict[str, Any]:
+        """Get space information."""
+        try:
+            result = self._client.get_space(space_key)
+            self._log.debug("space_retrieved", space_key=space_key)
+            return result
+
+        except Exception as exc:
+            self._handle_api_error(exc, f"get_space {space_key}")
+
+    def get_space_permissions(self, space_key: str) -> dict[str, Any]:
+        """Get all permissions configured for a space."""
+
+        def operation():
+            result = self._client.get_space_permissions(space_key)
+            count = len(result) if isinstance(result, (list, tuple)) else len(result or {})
+            self._log.debug("space_permissions_retrieved", space_key=space_key, count=count)
+            return result
+
+        return self._with_retry(operation, f"get_space_permissions {space_key}")
+
+    def set_permissions_to_user_for_space(
+        self,
+        space_key: str,
+        user_key: str,
+        *,
+        operations: list[str] | None = None,
+    ) -> dict[str, Any]:
+        """Grant permissions to a specific user for a space."""
+
+        def operation():
+            result = self._client.set_permissions_to_user_for_space(
+                space_key,
+                user_key,
+                operations=operations,
+            )
+            self._log.info(
+                "space_permissions_user_set",
+                space_key=space_key,
+                user_key=user_key,
+                operations=operations or [],
+            )
+            return result
+
+        return self._with_retry(operation, f"set_permissions_to_user_for_space {space_key} {user_key}")
+
+    def set_permissions_to_group_for_space(
+        self,
+        space_key: str,
+        group_name: str,
+        *,
+        operations: list[str] | None = None,
+    ) -> dict[str, Any]:
+        """Grant permissions to a group for a space."""
+
+        def operation():
+            result = self._client.set_permissions_to_group_for_space(
+                space_key,
+                group_name,
+                operations=operations,
+            )
+            self._log.info(
+                "space_permissions_group_set",
+                space_key=space_key,
+                group_name=group_name,
+                operations=operations or [],
+            )
+            return result
+
+        return self._with_retry(operation, f"set_permissions_to_group_for_space {space_key} {group_name}")
+
+    def set_permissions_to_anonymous_for_space(
+        self,
+        space_key: str,
+        *,
+        operations: list[str] | None = None,
+    ) -> dict[str, Any]:
+        """Grant permissions to anonymous users for a space."""
+
+        def operation():
+            result = self._client.set_permissions_to_anonymous_for_space(space_key, operations=operations)
+            self._log.info(
+                "space_permissions_anonymous_set",
+                space_key=space_key,
+                operations=operations or [],
+            )
+            return result
+
+        return self._with_retry(operation, f"set_permissions_to_anonymous_for_space {space_key}")
+
+    def set_permissions_to_multiple_items_for_space(
+        self,
+        space_key: str,
+        items: list[dict[str, Any]],
+    ) -> dict[str, Any]:
+        """Grant permissions to multiple users/groups in a single request."""
+
+        def operation():
+            result = self._client.set_permissions_to_multiple_items_for_space(space_key, items)
+            self._log.info(
+                "space_permissions_bulk_set",
+                space_key=space_key,
+                items=len(items),
+            )
+            return result
+
+        return self._with_retry(operation, f"set_permissions_to_multiple_items_for_space {space_key}")
+
+    def remove_permissions_from_user_for_space(self, space_key: str, user_key: str) -> dict[str, Any]:
+        """Remove all permissions granted to a user for a space."""
+
+        def operation():
+            result = self._client.remove_permissions_from_user_for_space(space_key, user_key)
+            self._log.info("space_permissions_user_removed", space_key=space_key, user_key=user_key)
+            return result
+
+        return self._with_retry(operation, f"remove_permissions_from_user_for_space {space_key} {user_key}")
+
+    def remove_permissions_from_group_for_space(self, space_key: str, group_name: str) -> dict[str, Any]:
+        """Remove all permissions granted to a group for a space."""
+
+        def operation():
+            result = self._client.remove_permissions_from_group_for_space(space_key, group_name)
+            self._log.info("space_permissions_group_removed", space_key=space_key, group_name=group_name)
+            return result
+
+        return self._with_retry(operation, f"remove_permissions_from_group_for_space {space_key} {group_name}")
+
+    def remove_permissions_from_anonymous_for_space(self, space_key: str) -> dict[str, Any]:
+        """Remove permissions granted to anonymous users for a space."""
+
+        def operation():
+            result = self._client.remove_permissions_from_anonymous_for_space(space_key)
+            self._log.info("space_permissions_anonymous_removed", space_key=space_key)
+            return result
+
+        return self._with_retry(operation, f"remove_permissions_from_anonymous_for_space {space_key}")
+
+    # --- User & Group Management ---
+
+    def get_all_groups(self, start: int = 0, limit: int = 1000) -> list[dict[str, Any]]:
+        """Get all groups in Confluence."""
+
+        def operation():
+            result = self._client.get_all_groups(start=start, limit=limit)
+            self._log.debug("groups_retrieved", count=len(result) if isinstance(result, list) else 0, start=start, limit=limit)
+            return result if isinstance(result, list) else []
+
+        return self._with_retry(operation, f"get_all_groups start={start} limit={limit}")
+
+    def get_group_members(self, group_name: str, start: int = 0, limit: int = 1000) -> list[dict[str, Any]]:
+        """Get members of a group."""
+
+        def operation():
+            result = self._client.get_group_members(group_name, start=start, limit=limit)
+            self._log.debug("group_members_retrieved", group_name=group_name, count=len(result) if isinstance(result, list) else 0)
+            return result if isinstance(result, list) else []
+
+        return self._with_retry(operation, f"get_group_members {group_name} start={start} limit={limit}")
+
+    def get_user_details_by_username(self, username: str, expand: str | None = None) -> dict[str, Any]:
+        """Get user details by username."""
+
+        def operation():
+            result = self._client.get_user_details_by_username(username, expand=expand)
+            self._log.debug("user_retrieved_by_username", username=username)
+            return result
+
+        return self._with_retry(operation, f"get_user_details_by_username {username}")
+
+    def get_user_details_by_userkey(self, userkey: str, expand: str | None = None) -> dict[str, Any]:
+        """Get user details by user key."""
+
+        def operation():
+            result = self._client.get_user_details_by_userkey(userkey, expand=expand)
+            self._log.debug("user_retrieved_by_userkey", userkey=userkey)
+            return result
+
+        return self._with_retry(operation, f"get_user_details_by_userkey {userkey}")
+
+    def change_user_password(self, username: str, password: str) -> None:
+        """Change user password."""
+
+        def operation():
+            self._client.change_user_password(username, password)
+            self._log.info("user_password_changed", username=username)
+            return None
+
+        return self._with_retry(operation, f"change_user_password {username}")
+
+    def add_user_to_group(self, username: str, group_name: str) -> None:
+        """Add user to group."""
+
+        def operation():
+            self._client.add_user_to_group(username, group_name)
+            self._log.info("user_added_to_group", username=username, group_name=group_name)
+            return None
+
+        return self._with_retry(operation, f"add_user_to_group {username} {group_name}")
+
+    def remove_user_from_group(self, username: str, group_name: str) -> None:
+        """Remove user from group."""
+
+        def operation():
+            self._client.remove_user_from_group(username, group_name)
+            self._log.info("user_removed_from_group", username=username, group_name=group_name)
+            return None
+
+        return self._with_retry(operation, f"remove_user_from_group {username} {group_name}")
+
+    # --- Export Operations ---
+
+    def export_page(self, page_id: str, api_version: str | None = None) -> bytes:
+        """Export page as PDF.
+
+        Note: The SDK auto-detects Cloud/Server mode based on client initialization.
+        The api_version parameter is accepted for CLI compatibility but not passed to SDK.
+        """
+
+        def operation():
+            # SDK auto-detects Cloud/Server mode, so we don't pass api_version
+            # The parameter is kept for CLI compatibility but ignored here
+            result = self._client.export_page(page_id)  # type: ignore[call-arg]
+            detected_mode = "cloud" if self._is_cloud else "server"
+            self._log.info("page_exported", page_id=page_id, detected_mode=detected_mode)
+            # SDK returns bytes or file path; ensure we return bytes
+            if isinstance(result, bytes):
+                return result
+            elif isinstance(result, str):
+                # If it's a file path, read it
+                with open(result, "rb") as f:
+                    return f.read()
+            else:
+                raise ConfluenceClientError(f"Unexpected export_page return type: {type(result)}", context={"page_id": page_id})
+
+        return self._with_retry(operation, f"export_page {page_id}")
+
+    def get_space_export(self, space_key: str, export_type: str) -> str:
+        """Get space export download URL."""
+
+        def operation():
+            result = self._client.get_space_export(space_key, export_type)
+            self._log.info("space_export_url_retrieved", space_key=space_key, export_type=export_type)
+            return result if isinstance(result, str) else str(result)
+
+        return self._with_retry(operation, f"get_space_export {space_key} {export_type}")
+
+    # --- Draft Management (Server-only) ---
+
+    def get_draft_page_by_id(self, page_id: str) -> dict[str, Any]:
+        """Get draft page by ID (Server-only)."""
+        if self._is_cloud:
+            raise ConfluenceClientError(
+                "get_draft_page_by_id is only available in Confluence Server/Data Center mode",
+                context={"page_id": page_id},
+            )
+
+        def operation():
+            result = self._client.get_draft_page_by_id(page_id)  # type: ignore[attr-defined]
+            self._log.debug("draft_page_retrieved", page_id=page_id)
+            return result
+
+        return self._with_retry(operation, f"get_draft_page_by_id {page_id}")
+
+    def get_all_draft_pages_from_space(self, space_key: str, limit: int = 25) -> list[dict[str, Any]]:
+        """Get all draft pages from a space (Server-only)."""
+        if self._is_cloud:
+            raise ConfluenceClientError(
+                "get_all_draft_pages_from_space is only available in Confluence Server/Data Center mode",
+                context={"space_key": space_key},
+            )
+
+        def operation():
+            result = self._client.get_all_draft_pages_from_space(space_key, limit=limit)  # type: ignore[attr-defined]
+            self._log.debug("draft_pages_retrieved", space_key=space_key, count=len(result) if isinstance(result, list) else 0)
+            return result if isinstance(result, list) else []
+
+        return self._with_retry(operation, f"get_all_draft_pages_from_space {space_key}")
+
+    def remove_page_as_draft(self, page_id: str) -> None:
+        """Remove page as draft (Server-only)."""
+        if self._is_cloud:
+            raise ConfluenceClientError(
+                "remove_page_as_draft is only available in Confluence Server/Data Center mode",
+                context={"page_id": page_id},
+            )
+
+        def operation():
+            self._client.remove_page_as_draft(page_id)  # type: ignore[attr-defined]
+            self._log.info("draft_page_removed", page_id=page_id)
+            return None
+
+        return self._with_retry(operation, f"remove_page_as_draft {page_id}")
+
+    # --- Cache Management (Server-only) ---
+
+    def get_cache_statistics(self) -> dict[str, Any]:
+        """Get cache statistics (Server-only)."""
+        if self._is_cloud:
+            raise ConfluenceClientError(
+                "get_cache_statistics is only available in Confluence Server/Data Center mode",
+                context={},
+            )
+
+        def operation():
+            # SDK doesn't have get_cache_statistics, use REST API directly
+            # Cache statistics endpoint: /rest/cache/1.0/stats
+            response = self.request(method="GET", path="/rest/cache/1.0/stats")
+            # SDK request method returns response object, extract JSON
+            if hasattr(response, 'json'):
+                result = response.json()
+            else:
+                result = response  # Already JSON dict
+            self._log.debug("cache_statistics_retrieved")
+            return result
+
+        return self._with_retry(operation, "get_cache_statistics")
+
+    def flush_cache(self, cache_name: str | None = None) -> None:
+        """Flush cache (Server-only).
+
+        Args:
+            cache_name: Optional cache name to flush specific cache. If None, flushes all caches.
+        """
+        if self._is_cloud:
+            raise ConfluenceClientError(
+                "flush_cache is only available in Confluence Server/Data Center mode",
+                context={"cache_name": cache_name},
+            )
+
+        def operation():
+            if cache_name:
+                # Flush specific cache package
+                self._client.clean_package_cache(cache_name=cache_name)  # type: ignore[attr-defined]
+                self._log.info("cache_flushed", cache_name=cache_name)
+            else:
+                # Flush all caches
+                self._client.clean_all_caches()  # type: ignore[attr-defined]
+                self._log.info("all_caches_flushed")
+
+        return self._with_retry(operation, f"flush_cache {cache_name or 'all'}")
+
+    def get_cache_size(self) -> dict[str, Any]:
+        """Get cache size information (Server-only)."""
+        if self._is_cloud:
+            raise ConfluenceClientError(
+                "get_cache_size is only available in Confluence Server/Data Center mode",
+                context={},
+            )
+
+        def operation():
+            # SDK doesn't have get_cache_size, use REST API directly
+            # Cache size endpoint: /rest/cache/1.0/size
+            response = self.request(method="GET", path="/rest/cache/1.0/size")
+            # SDK request method returns response object, extract JSON
+            if hasattr(response, 'json'):
+                result = response.json()
+            else:
+                result = response  # Already JSON dict
+            self._log.debug("cache_size_retrieved")
+            return result
+
+        return self._with_retry(operation, "get_cache_size")
+
+    # --- Advanced Content Operations ---
+
+    def get_page_ancestors(self, page_id: str) -> list[dict[str, Any]]:
+        """Get page ancestors (parent pages)."""
+
+        def operation():
+            result = self._client.get_page_ancestors(page_id)  # type: ignore[attr-defined]
+            self._log.debug("page_ancestors_retrieved", page_id=page_id, count=len(result) if isinstance(result, list) else 0)
+            return result if isinstance(result, list) else []
+
+        return self._with_retry(operation, f"get_page_ancestors {page_id}")
+
+    def move_page(self, page_id: str, target_title: str, position: str = "append") -> dict[str, Any]:
+        """Move page to a new location."""
+
+        def operation():
+            result = self._client.move_page(page_id, target_title, position=position)  # type: ignore[attr-defined]
+            self._log.info("page_moved", page_id=page_id, target_title=target_title, position=position)
+            return result
+
+        return self._with_retry(operation, f"move_page {page_id} {target_title}")
+
+    def get_tables_from_page(self, page_id: str) -> list[dict[str, Any]]:
+        """Extract tables from page."""
+
+        def operation():
+            result = self._client.get_tables_from_page(page_id)  # type: ignore[attr-defined]
+            self._log.debug("tables_extracted", page_id=page_id, count=len(result) if isinstance(result, list) else 0)
+            return result if isinstance(result, list) else []
+
+        return self._with_retry(operation, f"get_tables_from_page {page_id}")
+
+    def scrap_regex_from_page(self, page_id: str, regex: str) -> list[dict[str, Any]]:
+        """Extract regex matches from page."""
+
+        def operation():
+            result = self._client.scrap_regex_from_page(page_id, regex)  # type: ignore[attr-defined]
+            self._log.debug("regex_matches_extracted", page_id=page_id, pattern=regex, count=len(result) if isinstance(result, list) else 0)
+            return result if isinstance(result, list) else []
+
+        return self._with_retry(operation, f"scrap_regex_from_page {page_id} {regex}")
+
+    def get_all_restrictions_for_content(self, content_id: str) -> dict[str, Any]:
+        """Get all restrictions for content."""
+
+        def operation():
+            result = self._client.get_all_restrictions_for_content(content_id)  # type: ignore[attr-defined]
+            self._log.debug("content_restrictions_retrieved", content_id=content_id)
+            return result
+
+        return self._with_retry(operation, f"get_all_restrictions_for_content {content_id}")
+
+    # --- History & Versioning ---
+
+    def history(self, page_id: str) -> dict[str, Any]:
+        """Get page history."""
+
+        def operation():
+            result = self._client.history(page_id)  # type: ignore[attr-defined]
+            self._log.debug("page_history_retrieved", page_id=page_id)
+            return result
+
+        return self._with_retry(operation, f"history {page_id}")
+
+    def get_content_history_by_version_number(self, page_id: str, version: int) -> dict[str, Any]:
+        """Get specific version of content."""
+
+        def operation():
+            result = self._client.get_content_history_by_version_number(page_id, version)  # type: ignore[attr-defined]
+            self._log.debug("content_version_retrieved", page_id=page_id, version=version)
+            return result
+
+        return self._with_retry(operation, f"get_content_history_by_version_number {page_id} {version}")
+
+    def remove_content_history(self, page_id: str, version: int) -> None:
+        """Remove content history (experimental)."""
+
+        def operation():
+            self._client.remove_content_history(page_id, version)  # type: ignore[attr-defined]
+            self._log.info("content_history_removed", page_id=page_id, version=version)
+            return None
+
+        return self._with_retry(operation, f"remove_content_history {page_id} {version}")
+
+    def archive_space(self, space_key: str) -> dict[str, Any]:
+        """Archive a Confluence space."""
+
+        def operation():
+            result = self._client.archive_space(space_key)
+            self._log.info("space_archived", space_key=space_key)
+            return result or {"status": "archived"}
+
+        return self._with_retry(operation, f"archive_space {space_key}")
+
+    def get_trashed_contents_by_space(
+        self,
+        space_key: str,
+        *,
+        cursor: str | None = None,
+        expand: str | None = None,
+        limit: int = 100,
+    ) -> dict[str, Any]:
+        """List trashed content for a space."""
+
+        def operation():
+            result = self._client.get_trashed_contents_by_space(
+                space_key,
+                cursor=cursor,
+                expand=expand,
+                limit=limit,
+            )
+            count = len(result.get("results", [])) if isinstance(result, dict) else 0
+            self._log.debug(
+                "space_trash_listed",
+                space_key=space_key,
+                count=count,
+                cursor=cursor,
+                limit=limit,
+            )
+            return result
+
+        return self._with_retry(operation, f"get_trashed_contents_by_space {space_key}")
+
+    def remove_trashed_contents_by_space(self, space_key: str) -> dict[str, Any]:
+        """Remove trashed content for a space."""
+
+        def operation():
+            result = self._client.remove_trashed_contents_by_space(space_key)
+            self._log.info("space_trash_cleared", space_key=space_key)
+            return result or {"status": "removed"}
+
+        return self._with_retry(operation, f"remove_trashed_contents_by_space {space_key}")
+
+    def get_child_pages(self, page_id: str) -> list[dict[str, Any]]:
+        """Get child pages of a page."""
+        try:
+            result = self._client.get_child_pages(page_id)
+            # Convert generator to list if needed
+            if hasattr(result, '__iter__') and not isinstance(result, (list, tuple, dict)):
+                result = list(result)
+            self._log.debug("child_pages_retrieved", page_id=page_id, count=len(result) if result else 0)
+            return result or []
+
+        except Exception as exc:
+            self._handle_api_error(exc, f"get_child_pages {page_id}")
+
+    def get_page_by_title(self, space_key: str, title: str) -> dict[str, Any] | None:
+        """Get a page by space and title."""
+        try:
+            result = self._client.get_page_by_title(space_key, title)
+            self._log.debug("page_retrieved_by_title", space_key=space_key, title=title)
+            return result
+
+        except Exception as exc:
+            self._handle_api_error(exc, f"get_page_by_title {space_key}/{title}")
+
+    def get_attachments(self, page_id: str) -> list[dict[str, Any]]:
+        """Get attachments for a page."""
+        try:
+            result = self._client.get_attachments_from_content(page_id)
+            self._log.debug("attachments_retrieved", page_id=page_id, count=len(result) if result else 0)
+            return result or []
+
+        except Exception as exc:
+            self._handle_api_error(exc, f"get_attachments {page_id}")
+
+    def get_attachment_content(self, attachment_id: str) -> bytes:
+        """Get attachment content by ID."""
+        try:
+            result = self._client.get_attachment_data(attachment_id)
+            self._log.debug("attachment_content_retrieved", attachment_id=attachment_id)
+            return result
+
+        except Exception as exc:
+            self._handle_api_error(exc, f"get_attachment_content {attachment_id}")
+
+    def update_attachment_data(
+        self,
+        page_id: str,
+        attachment_id: str,
+        filename: str,
+        content: bytes,
+        content_type: str | None = None,
+        *,
+        comment: str | None = None,
+    ) -> dict[str, Any]:
+        """Update an existing attachment.
+
+        According to atlassian-python-api docs, attach_content automatically updates
+        if the file exists, versioning the new file and keeping the old one.
+        """
+        def operation():
+            # Use attach_content - it automatically updates if file exists
+            # See: https://atlassian-python-api.readthedocs.io/confluence.html#
+            result = self._client.attach_content(
+                content=content,
+                name=filename,
+                content_type=content_type or "application/octet-stream",
+                page_id=page_id,
+                comment=comment,
+            )
+            self._log.info("attachment_updated", page_id=page_id, attachment_id=attachment_id, filename=filename)
+            return result
+
+        return self._with_retry(operation, f"update_attachment {attachment_id}")
+
+    def delete_attachment_by_id(self, page_id: str, attachment_id: str, version: int | None = None) -> None:
+        """Delete an attachment by ID (historic versions only).
+
+        The Atlassian SDK's ``delete_attachment_by_id`` endpoint only removes versions
+        strictly lower than the current one, so callers should provide ``version`` when
+        targeting a specific revision. Cloud docs:
+        https://atlassian-python-api.readthedocs.io/confluence.html#confluence.Confluence.delete_attachment_by_id
+        """
+        try:
+            versions_payload = self._client.get_attachment_history(attachment_id) or []
+        except Exception:  # pragma: no cover - defensive
+            versions_payload = []
+
+        versions = []
+        for item in versions_payload:
+            if isinstance(item, dict):
+                number = item.get("number")
+                if isinstance(number, int):
+                    versions.append(number)
+
+        if version is not None:
+            versions = [ver for ver in versions if ver == version]
+
+        if not versions:
+            if version is not None:
+                versions = [version]
+            else:
+                raise ConfluenceClientError(
+                    f"No attachment versions found for {attachment_id}. Specify --version explicitly.",
+                    context={"attachment_id": attachment_id, "page_id": page_id},
+                )
+
+        for ver in sorted(set(versions), reverse=True):
+            try:
+                self._client.delete_attachment_by_id(attachment_id, ver)
+                self._log.info(
+                    "attachment_version_deleted",
+                    page_id=page_id,
+                    attachment_id=attachment_id,
+                    version=ver,
+                )
+            except Exception as exc:
+                self._handle_api_error(exc, f"delete_attachment {attachment_id} (version {ver})")
+
+    def delete_attachment(self, page_id: str, filename: str, version: int | None = None) -> None:
+        """Delete the latest version of an attachment by filename.
+
+        Mirrors :py:meth:`Confluence.delete_attachment` from the Atlassian SDK.
+        """
+
+        try:
+            self._client.delete_attachment(page_id, filename, version=version)
+            self._log.info(
+                "attachment_deleted",
+                page_id=page_id,
+                filename=filename,
+                version=version,
+            )
+        except Exception as exc:
+            self._handle_api_error(exc, f"delete_attachment {filename}")
+
+    def add_comment(self, page_id: str, body: str) -> dict[str, Any]:
+        """Add a comment to a page."""
+        try:
+            result = self._client.add_comment(page_id, body)
+            self._log.info("comment_added", page_id=page_id)
+            return result
+
+        except Exception as exc:
+            self._handle_api_error(exc, f"add_comment {page_id}")
+
+    def get_page_history(self, page_id: str) -> dict[str, Any]:
+        """Get page version history."""
+        try:
+            result = self._client.get_history(page_id)
+            self._log.debug("page_history_retrieved", page_id=page_id)
+            return result
+
+        except Exception as exc:
+            self._handle_api_error(exc, f"get_page_history {page_id}")
+
+    def close(self) -> None:
+        """Close the client (cleanup method for compatibility)."""
+        # atlassian-python-api doesn't require explicit cleanup
+        pass
+
+    def __enter__(self) -> ConfluenceClient:
+        return self
+
+    def __exit__(self, exc_type, exc, tb) -> None:
+        self.close()
+
+
+__all__ = ["ConfluenceClient"]