@ngocsangairvds/vsaf 4.0.5 → 4.0.7

package/skills/vds-skill/vds-scripts/confluence_orchestrator/src/confluence_orchestrator/http.py

@@ -0,0 +1,1850 @@
+"""Confluence client wrapper using atlassian-python-api for consistency."""
+
+from __future__ import annotations
+
+import inspect
+import time
+from collections.abc import Callable
+from datetime import UTC, datetime, timedelta
+from typing import TYPE_CHECKING, Any, TypeVar
+from urllib.parse import parse_qs, urlparse
+
+import httpx
+import structlog
+from vds_platform_core.credentials import resolve_secret
+
+try:  # Prefer new-style Atlassian clients when available
+    from atlassian.confluence import ConfluenceCloud as AtlassianConfluenceCloud  # type: ignore[attr-defined]
+    from atlassian.confluence import ConfluenceServer as AtlassianConfluenceServer  # type: ignore[attr-defined]
+except ImportError:  # Fall back to legacy class
+    from atlassian import Confluence as AtlassianConfluenceCloud  # type: ignore
+
+    AtlassianConfluenceServer = AtlassianConfluenceCloud
+
+from .errors import (
+    AuthError,
+    ClientPermissionError,
+    ConflictError,
+    ConfluenceDegradedWriteError,
+    RateLimitError,
+    ResponseError,
+    RetryError,
+    TransportError,
+    VDSClientError,
+)
+
+if TYPE_CHECKING:
+    from .config import ConfluenceSettings
+
+T = TypeVar("T")
+
+# Write operations blocked when the client is in degraded mode.
+_WRITE_OPS: frozenset[str] = frozenset(
+    {
+        "create_page",
+        "update_page",
+        "delete_page",
+        "upload_attachment",
+        "update_attachment",
+        "delete_attachment",
+        "add_attachment",
+        "add_comment",
+    }
+)
+
+
+def _escape_cql_literal(value: str) -> str:
+    return value.replace("\\", "\\\\").replace('"', '\\"')
+
+
+def _coerce_utc_datetime(value: datetime | str) -> datetime:
+    if isinstance(value, datetime):
+        dt_value = value
+    else:
+        normalized = value.strip()
+        if normalized.endswith("Z"):
+            normalized = normalized[:-1] + "+00:00"
+        try:
+            dt_value = datetime.fromisoformat(normalized)
+        except ValueError as exc:
+            raise VDSClientError(
+                "Invalid incremental high-water-mark timestamp",
+                context={"value": value},
+            ) from exc
+    if dt_value.tzinfo is None:
+        return dt_value.replace(tzinfo=UTC)
+    return dt_value.astimezone(UTC)
+
+
+def _build_lastmodified_cql_clause(
+    last_modified_after: datetime | str | None,
+    *,
+    overlap_minutes: int = 0,
+) -> str | None:
+    if last_modified_after is None:
+        return None
+    overlap = max(int(overlap_minutes), 0)
+    cursor = _coerce_utc_datetime(last_modified_after)
+    if overlap:
+        cursor = cursor - timedelta(minutes=overlap)
+    return f'lastmodified >= "{cursor.strftime("%Y-%m-%d %H:%M")}"'
+
+
+def _build_space_type_lastmodified_cql(
+    *,
+    space_key: str | None = None,
+    content_type: str | None = None,
+    last_modified_after: datetime | str | None = None,
+    overlap_minutes: int = 0,
+) -> str:
+    cql_parts: list[str] = []
+    if space_key:
+        cql_parts.append(f'space = "{_escape_cql_literal(space_key)}"')
+    if content_type:
+        cql_parts.append(f'type = "{_escape_cql_literal(content_type)}"')
+    last_modified_clause = _build_lastmodified_cql_clause(
+        last_modified_after,
+        overlap_minutes=overlap_minutes,
+    )
+    if last_modified_clause:
+        cql_parts.append(last_modified_clause)
+    if not cql_parts:
+        raise VDSClientError(
+            "At least one of space_key, content_type, or last_modified_after must be provided",
+            context={},
+        )
+    query = " AND ".join(cql_parts)
+    if last_modified_clause:
+        query = f"{query} ORDER BY lastmodified ASC"
+    return query
+
+
+class ConfluenceHttpClient:
+    def __init__(
+        self,
+        settings: ConfluenceSettings,
+        *,
+        server: str = "internal",
+        client: httpx.Client | None = None,
+    ) -> None:
+        token = settings.token_for(server)
+        if not token:
+            raise AuthError(
+                f"Token for server '{server}' is missing.",
+                context={"server": server},
+            )
+
+        self._settings = settings
+        self._server = server
+        self._token = token
+        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 get_runtime_telemetry(self) -> dict[str, Any]:
+        """Return telemetry snapshot (stub for crawl_tree compatibility).
+
+        ConfluenceClient operates in degraded-mode (read-only) or normal mode.
+        This stub provides a compatible interface for telemetry consumers.
+        Actual retry/telemetry instrumentation would require adopting
+        platform_core.with_retry (httpx.AsyncClient), which is a larger
+        refactor beyond Phase 7 scope.
+        """
+        return {
+            "adaptive_throttle": None,
+            "recent_retry_events": [],
+            "latency_ms": None,
+            "mode": "degraded" if self._degraded else "normal",
+        }
+
+    def request(self, method: str, path: str, **kwargs: Any) -> httpx.Response:
+        try:
+            response = self._client.request(method, path, **kwargs)
+        except httpx.HTTPError as exc:  # pragma: no cover - network errors
+            raise TransportError(f"HTTP transport error: {exc}") from exc
+
+        if response.status_code < 400:
+            return response
+
+        if response.status_code in {401, 403}:
+            raise AuthError(
+                "Authentication failed",
+                context={"status_code": response.status_code},
+            )
+        if response.status_code == 409:
+            raise ConflictError(
+                "Request conflicted with existing state",
+                context={"status_code": response.status_code},
+            )
+        raise ResponseError(
+            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 = None,
+    ) -> None:
+        self._settings = settings
+        self._server = server or settings.default_server
+        self._timeout = timeout or settings.http_timeout
+
+        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
+        # Token (Bearer/PAT) takes priority over username+password to avoid 401s
+        # when Basic auth is disabled on the server.
+        auth_kwargs: dict[str, Any] = {"url": base_url, "timeout": self._timeout}
+        if self._is_cloud:
+            if token:
+                auth_kwargs["token"] = token
+            elif settings.username and settings.password:
+                auth_kwargs["username"] = settings.username
+                auth_kwargs["password"] = resolve_secret(settings.password)
+            else:
+                raise AuthError(
+                    f"No credentials available for cloud server '{self._server}'. "
+                    "Provide an API token or VDS_USERNAME+VDS_PASSWORD.",
+                    context={"server": self._server},
+                )
+        elif token:
+            # PATs supported on Confluence Server/Data Center
+            auth_kwargs["token"] = token
+        elif settings.username and settings.password:
+            auth_kwargs["username"] = settings.username
+            auth_kwargs["password"] = resolve_secret(settings.password)
+        else:
+            raise AuthError(
+                f"No credentials available for server '{self._server}'. "
+                "Provide a CONFLUENCE token or VDS_USERNAME+VDS_PASSWORD.",
+                context={"server": self._server},
+            )
+        client_params = set(self._safe_signature_params(client_cls))
+        supports_kwargs = False
+        try:
+            signature = inspect.signature(client_cls)
+            supports_kwargs = any(
+                param.kind is inspect.Parameter.VAR_KEYWORD for param in signature.parameters.values()
+            )
+        except (TypeError, ValueError):
+            supports_kwargs = False
+        if "cloud" in client_params or supports_kwargs:
+            # Legacy Confluence() requires explicit cloud flag when URL already includes /wiki.
+            auth_kwargs["cloud"] = self._is_cloud
+
+        try:
+            self._client = client_cls(**auth_kwargs)
+        except Exception as exc:
+            raise TransportError(
+                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._retry_max_wait = 30.0
+        self._create_params = set(self._safe_signature_params(self._client.create_page))
+        self._update_params = set(self._safe_signature_params(self._client.update_page))
+        # FR-172: degraded mode — set True on transport errors to block writes.
+        self._degraded: bool = False
+
+    # ------------------------------------------------------------------
+    # FR-172: Degraded mode API
+    # ------------------------------------------------------------------
+
+    @property
+    def is_degraded(self) -> bool:
+        """True when the client has been marked degraded due to transport errors."""
+        return self._degraded
+
+    def mark_degraded(self) -> None:
+        """Mark the client as degraded, blocking all subsequent write operations."""
+        self._degraded = True
+
+    def get_runtime_telemetry(self) -> dict[str, Any]:
+        """Return telemetry snapshot (stub for crawl_tree compatibility).
+
+        ConfluenceClient operates in degraded-mode (read-only) or normal mode.
+        This stub provides a compatible interface for telemetry consumers.
+        Actual retry/telemetry instrumentation would require adopting
+        platform_core.with_retry (httpx.AsyncClient), which is a larger
+        refactor beyond Phase 7 scope.
+        """
+        return {
+            "adaptive_throttle": None,
+            "recent_retry_events": [],
+            "latency_ms": None,
+            "mode": "degraded" if self._degraded else "normal",
+        }
+
+    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 []
+
+    @staticmethod
+    def _extract_pagination_marker(payload: dict[str, Any]) -> tuple[int | None, str | None]:
+        """Extract pagination start/token markers from SDK payloads."""
+        next_start: int | None = None
+        next_token: str | None = None
+
+        links = payload.get("_links")
+        next_link: str | None = None
+        if isinstance(links, dict) and isinstance(links.get("next"), str):
+            next_link = links["next"]
+        elif isinstance(payload.get("next"), str):
+            next_link = payload["next"]
+
+        if next_link:
+            next_token = next_link
+            query = urlparse(next_link).query
+            if not query and "=" in next_link and "?" not in next_link:
+                query = next_link
+            params = parse_qs(query)
+            start_values = params.get("start")
+            if start_values:
+                try:
+                    next_start = int(start_values[0])
+                except (TypeError, ValueError):
+                    next_start = None
+            cursor_values = params.get("cursor")
+            if cursor_values and cursor_values[0]:
+                next_token = cursor_values[0]
+
+        for key in ("nextCursor", "next_cursor", "cursor"):
+            value = payload.get(key)
+            if isinstance(value, str) and value.strip():
+                next_token = value.strip()
+                break
+
+        raw_start = payload.get("start")
+        if next_start is None and isinstance(raw_start, int):
+            next_start = raw_start
+
+        return next_start, next_token
+
+    @staticmethod
+    def _require_dict(value: Any, operation: str) -> dict[str, Any]:
+        if isinstance(value, dict):
+            return value
+        raise VDSClientError(
+            f"{operation} returned unexpected payload type",
+            context={"operation": operation, "payload_type": type(value).__name__},
+        )
+
+    @staticmethod
+    def _coerce_dict(value: Any) -> dict[str, Any]:
+        if isinstance(value, dict):
+            return value
+        return {"value": value}
+
+    @staticmethod
+    def _coerce_list_of_dicts(value: Any) -> list[dict[str, Any]]:
+        if isinstance(value, list):
+            return [item for item in value if isinstance(item, dict)]
+        return []
+
+    @staticmethod
+    def _coerce_bytes(value: Any) -> bytes:
+        if isinstance(value, bytes):
+            return value
+        if isinstance(value, str):
+            return value.encode("utf-8")
+        raise VDSClientError(
+            "Unexpected binary payload type",
+            context={"payload_type": type(value).__name__},
+        )
+
+    @staticmethod
+    def _coerce_str(value: Any) -> str:
+        if isinstance(value, str):
+            return value
+        return str(value)
+
+    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 AuthError(f"Authentication failed during {operation}", context={"error": str(error)})
+        elif "forbidden" in error_str or "403" in error_str:
+            raise AuthError(f"Access forbidden during {operation}", context={"error": str(error)})
+        elif "rate limit" in error_str or "429" in error_str:
+            raise RateLimitError(
+                f"Rate limited during {operation}",
+                retry_after=None,
+                context={"error": str(error)},
+            )
+        elif "conflict" in error_str or "409" in error_str:
+            raise ConflictError(f"Conflict during {operation}", context={"error": str(error)})
+        elif "server error" in error_str or "500" in error_str:
+            raise ResponseError(
+                f"Server error during {operation}",
+                status_code=500,
+                context={"error": str(error)},
+            )
+        else:
+            raise VDSClientError(f"API error during {operation}: {error}", context={"error": str(error)})
+
+    def _with_retry(self, operation: Callable[[], T], operation_name: str) -> T:
+        """Execute an operation with retry logic using instance settings."""
+        op_base = (operation_name or "").strip().lower().split(" ", 1)[0]
+        if self._degraded and op_base in _WRITE_OPS:
+            raise ConfluenceDegradedWriteError(operation_name)
+        for attempt in range(self._max_retries + 1):
+            try:
+                return operation()
+            except Exception as exc:
+                try:
+                    self._handle_api_error(exc, operation_name)
+                except (TransportError, RateLimitError) 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),
+                        )
+                        raise RetryError(
+                            f"Retry attempts exhausted: {retry_exc}",
+                            attempts=self._max_retries,
+                            context={"original_error": str(retry_exc), "operation": operation_name},
+                        ) from retry_exc
+
+                    wait_time = min(
+                        max(self._retry_backoff_factor, 0.0) * (2**attempt),
+                        self._retry_max_wait,
+                    )
+                    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 VDSClientError:
+                    raise
+        raise VDSClientError(
+            "Retry loop exited without returning result",
+            context={"operation": operation_name},
+        )
+
+    def get_page(self, page_id: str, expand: list[str] | None = None) -> dict[str, Any]:
+        """Get a page by ID."""
+
+        def operation() -> dict[str, Any]:
+            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 self._require_dict(result, "get_page")
+
+        return self._with_retry(operation, f"get_page {page_id}")
+
+    def search_cql(
+        self, cql: str, limit: int = 25, start: int = 0, expand: list[str] | None = None, **kwargs: Any
+    ) -> dict[str, Any]:
+        """Search using CQL.
+
+        Bypasses the ``atlassian`` SDK's ``cql()`` method entirely because it
+        uses ``if start:`` which is falsy for ``start=0``, causing the param to
+        be omitted.  Instead we call ``rest/api/search`` directly with an
+        explicit ``params`` dict that always includes ``start``.
+
+        Without ``start`` in the request, some Confluence Server versions respond
+        with ``java.lang.IllegalArgumentException: parameters should not be empty``.
+        """
+
+        def operation() -> dict[str, Any]:
+            params: dict[str, Any] = {"cql": cql, "start": int(start)}
+            if limit is not None:
+                params["limit"] = int(limit)
+            if expand:
+                params["expand"] = ",".join(expand)
+            params.update(kwargs)
+            result = self._client.get("rest/api/search", params=params)
+            self._log.debug("cql_search_completed", cql=cql, limit=limit, start=start)
+            return self._require_dict(result, "search_cql")
+
+        return self._with_retry(operation, f"cql_search {cql}")
+
+    def probe_reachable(self) -> dict[str, Any]:
+        """Run a minimal SDK-backed reachability probe against the selected base URL.
+
+        The probe intentionally uses the same REST search path as normal CQL
+        reads so Phase 153's explicit ``start=0`` handling stays exercised.
+        Callers should treat success as "the configured Confluence base URL
+        answered an authenticated SDK request", not as a guarantee that every
+        later content operation will be fast.
+        """
+
+        return self.search_cql("type=page", limit=1, start=0)
+
+    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() -> dict[str, Any]:
+            # Bypass self._client.cql() which has `if start:` falsy check.
+            params: dict[str, Any] = {"cql": cql, "start": int(start)}
+            if limit is not None:
+                params["limit"] = int(limit)
+            expand_str = ",".join(expand) if expand else None
+            if expand_str:
+                params["expand"] = expand_str
+            if excerpt:
+                params["excerpt"] = excerpt
+            params.update(kwargs)
+            result = self._client.get("rest/api/search", params=params)
+            self._log.debug("cql_advanced_search_completed", cql=cql, limit=limit, start=start)
+            return self._require_dict(result, "cql_advanced")
+
+        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,
+        last_modified_after: datetime | str | None = None,
+        overlap_minutes: int = 0,
+        **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
+            last_modified_after: Optional high-water-mark timestamp for incremental crawl
+            overlap_minutes: Optional overlap buffer minutes for high-water-mark queries
+            **kwargs: Additional options passed to CQL search
+        """
+        cql = _build_space_type_lastmodified_cql(
+            space_key=space_key,
+            content_type=content_type,
+            last_modified_after=last_modified_after,
+            overlap_minutes=overlap_minutes,
+        )
+        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() -> dict[str, Any]:
+            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)
+            payload = self._require_dict(result, "create_page")
+            self._log.info("page_created", space_key=space_key, title=title, page_id=payload.get("id"))
+            return payload
+
+        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,
+        parent_id: str | None = None,
+        **kwargs: Any,
+    ) -> dict[str, Any]:
+        """Update an existing page."""
+
+        def operation() -> dict[str, Any]:
+            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
+            if parent_id is not None and "parent_id" in self._update_params:
+                call_kwargs["parent_id"] = parent_id
+            result = self._client.update_page(page_id, title, body, **call_kwargs)
+            self._log.info("page_updated", page_id=page_id, title=title)
+            return self._require_dict(result, "update_page")
+
+        return self._with_retry(operation, f"update_page {page_id}")
+
+    def delete_page(self, page_id: str) -> None:
+        """Delete a page."""
+        if self._degraded:
+            raise ConfluenceDegradedWriteError(f"delete_page {page_id}")
+        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 ClientPermissionError(
+                    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}")
+            raise
+
+    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() -> dict[str, Any]:
+            # 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 self._coerce_dict(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 self._require_dict(result, "get_space")
+
+        except Exception as exc:
+            self._handle_api_error(exc, f"get_space {space_key}")
+            raise
+
+    def get_space_permissions(self, space_key: str) -> dict[str, Any]:
+        """Get all permissions configured for a space."""
+
+        def operation() -> dict[str, Any]:
+            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 self._coerce_dict(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() -> dict[str, Any]:
+            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 self._coerce_dict(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() -> dict[str, Any]:
+            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 self._coerce_dict(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() -> dict[str, Any]:
+            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 self._coerce_dict(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."""
+
+        if not items:
+            raise VDSClientError(
+                "Bulk permissions payload is empty",
+                context={"space_key": space_key},
+            )
+
+        def _normalize_item(item: dict[str, Any], index: int) -> tuple[str, str | None, list[str]]:
+            raw_operations = item.get("operations")
+            if raw_operations is None:
+                operations: list[str] = []
+            elif isinstance(raw_operations, list) and all(isinstance(op, str) for op in raw_operations):
+                operations = [op.strip() for op in raw_operations if op.strip()]
+            else:
+                raise VDSClientError(
+                    "Invalid operations in bulk permissions item",
+                    context={"space_key": space_key, "index": index},
+                )
+
+            target_type: str | None = None
+            target_value: str | None = None
+
+            target = item.get("target")
+            if isinstance(target, dict):
+                raw_type = target.get("type")
+                if isinstance(raw_type, str):
+                    target_type = raw_type.strip().lower()
+                raw_value = target.get("value")
+                if raw_value is None:
+                    raw_value = target.get("key")
+                if raw_value is None:
+                    raw_value = target.get("name")
+                if raw_value is not None:
+                    target_value = str(raw_value).strip()
+
+            if target_type is None and isinstance(item.get("target_type"), str):
+                target_type = str(item["target_type"]).strip().lower()
+            if target_type is None and isinstance(item.get("user_key"), str):
+                target_type = "user"
+                target_value = item["user_key"].strip()
+            if target_type is None and isinstance(item.get("group_name"), str):
+                target_type = "group"
+                target_value = item["group_name"].strip()
+            if target_type is None and item.get("anonymous") is True:
+                target_type = "anonymous"
+
+            if target_type not in {"user", "group", "anonymous"}:
+                raise VDSClientError(
+                    "Bulk permission item target is invalid",
+                    context={"space_key": space_key, "index": index},
+                )
+            if target_type in {"user", "group"} and not target_value:
+                raise VDSClientError(
+                    "Bulk permission item requires target value for user/group",
+                    context={"space_key": space_key, "index": index, "target_type": target_type},
+                )
+
+            return target_type, target_value, operations
+
+        normalized_items = [_normalize_item(item, index) for index, item in enumerate(items)]
+
+        def operation() -> dict[str, Any]:
+            bulk_method = getattr(self._client, "set_permissions_to_multiple_items_for_space", None)
+            bulk_params = set(self._safe_signature_params(bulk_method)) if callable(bulk_method) else set()
+
+            mode: str
+            if callable(bulk_method) and "items" in bulk_params:
+                result = bulk_method(space_key, items=items)
+                mode = "native-items"
+            elif callable(bulk_method) and ("user_key" in bulk_params or "group_name" in bulk_params):
+                compat_results: list[dict[str, Any]] = []
+                for target_type, target_value, operations in normalized_items:
+                    kwargs: dict[str, Any] = {"operations": operations}
+                    if target_type == "user":
+                        kwargs["user_key"] = target_value
+                    elif target_type == "group":
+                        kwargs["group_name"] = target_value
+                    compat_results.append(self._coerce_dict(bulk_method(space_key, **kwargs)))
+                result = {
+                    "mode": "legacy-bulk",
+                    "items_processed": len(normalized_items),
+                    "results": compat_results,
+                }
+                mode = "legacy-bulk"
+            else:
+                compat_results = []
+                for target_type, target_value, operations in normalized_items:
+                    if target_type == "user":
+                        compat_results.append(
+                            self._coerce_dict(
+                                self._client.set_permissions_to_user_for_space(  # type: ignore[attr-defined]
+                                    space_key,
+                                    target_value,
+                                    operations=operations,
+                                )
+                            )
+                        )
+                    elif target_type == "group":
+                        compat_results.append(
+                            self._coerce_dict(
+                                self._client.set_permissions_to_group_for_space(  # type: ignore[attr-defined]
+                                    space_key,
+                                    target_value,
+                                    operations=operations,
+                                )
+                            )
+                        )
+                    else:
+                        compat_results.append(
+                            self._coerce_dict(
+                                self._client.set_permissions_to_anonymous_for_space(  # type: ignore[attr-defined]
+                                    space_key,
+                                    operations=operations,
+                                )
+                            )
+                        )
+                result = {
+                    "mode": "expanded-fallback",
+                    "items_processed": len(normalized_items),
+                    "results": compat_results,
+                }
+                mode = "expanded-fallback"
+
+            self._log.info(
+                "space_permissions_bulk_set",
+                space_key=space_key,
+                items=len(normalized_items),
+                mode=mode,
+            )
+            return self._coerce_dict(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() -> dict[str, Any]:
+            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 self._coerce_dict(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() -> dict[str, Any]:
+            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 self._coerce_dict(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() -> dict[str, Any]:
+            result = self._client.remove_permissions_from_anonymous_for_space(space_key)
+            self._log.info("space_permissions_anonymous_removed", space_key=space_key)
+            return self._coerce_dict(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() -> list[dict[str, Any]]:
+            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() -> list[dict[str, Any]]:
+            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() -> dict[str, Any]:
+            result = self._client.get_user_details_by_username(username, expand=expand)
+            self._log.debug("user_retrieved_by_username", username=username)
+            return self._require_dict(result, "get_user_details_by_username")
+
+        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() -> dict[str, Any]:
+            result = self._client.get_user_details_by_userkey(userkey, expand=expand)
+            self._log.debug("user_retrieved_by_userkey", userkey=userkey)
+            return self._require_dict(result, "get_user_details_by_userkey")
+
+        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() -> None:
+            self._client.change_user_password(username, password)
+            self._log.info("user_password_changed", username=username)
+
+        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() -> None:
+            self._client.add_user_to_group(username, group_name)
+            self._log.info("user_added_to_group", username=username, group_name=group_name)
+
+        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 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 self._coerce_bytes(result)
+            elif isinstance(result, str):
+                # If it's a file path, read it
+                with open(result, "rb") as f:
+                    return f.read()
+            else:
+                raise VDSClientError(
+                    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() -> str:
+            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 VDSClientError(
+                "get_draft_page_by_id is only available in Confluence Server/Data Center mode",
+                context={"page_id": page_id},
+            )
+
+        def operation() -> dict[str, Any]:
+            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 self._require_dict(result, "get_draft_page_by_id")
+
+        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 VDSClientError(
+                "get_all_draft_pages_from_space is only available in Confluence Server/Data Center mode",
+                context={"space_key": space_key},
+            )
+
+        def operation() -> list[dict[str, Any]]:
+            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 VDSClientError(
+                "remove_page_as_draft is only available in Confluence Server/Data Center mode",
+                context={"page_id": page_id},
+            )
+
+        def operation() -> None:
+            self._client.remove_page_as_draft(page_id)  # type: ignore[attr-defined]
+            self._log.info("draft_page_removed", page_id=page_id)
+
+        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 VDSClientError(
+                "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 self._coerce_dict(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 VDSClientError(
+                "flush_cache is only available in Confluence Server/Data Center mode",
+                context={"cache_name": cache_name},
+            )
+
+        def operation() -> None:
+            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 VDSClientError(
+                "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 self._coerce_dict(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() -> list[dict[str, Any]]:
+            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",
+        *,
+        space_key: str | None = None,
+    ) -> dict[str, Any]:
+        """Move page to a new location."""
+
+        def operation() -> dict[str, Any]:
+            move_page_method = getattr(self._client, "move_page", None)
+            if not callable(move_page_method):
+                raise VDSClientError("SDK does not support move_page")
+
+            move_params = set(self._safe_signature_params(move_page_method))
+            if "space_key" in move_params and "page_id" in move_params:
+                resolved_space_key = space_key
+                if not resolved_space_key and hasattr(self._client, "get_page_space"):
+                    raw_space_key = self._client.get_page_space(page_id)  # type: ignore[attr-defined]
+                    if isinstance(raw_space_key, str) and raw_space_key.strip():
+                        resolved_space_key = raw_space_key.strip()
+                if not resolved_space_key:
+                    page = self._client.get_page_by_id(page_id, expand="space")
+                    if isinstance(page, dict):
+                        page_space = page.get("space")
+                        if isinstance(page_space, dict):
+                            raw_space_key = page_space.get("key")
+                            if raw_space_key:
+                                resolved_space_key = str(raw_space_key).strip()
+                if not resolved_space_key:
+                    raise VDSClientError(
+                        "Unable to resolve space key for move_page",
+                        context={"page_id": page_id},
+                    )
+
+                legacy_position = {"before": "above", "after": "below"}.get(position, position)
+                result = move_page_method(
+                    resolved_space_key,
+                    page_id,
+                    target_title=target_title,
+                    position=legacy_position,
+                )
+                self._log.info(
+                    "page_moved",
+                    page_id=page_id,
+                    target_title=target_title,
+                    position=position,
+                    resolved_position=legacy_position,
+                    space_key=resolved_space_key,
+                    move_contract="legacy",
+                )
+                return self._coerce_dict(result)
+
+            result = move_page_method(page_id, target_title, position=position)
+            self._log.info(
+                "page_moved",
+                page_id=page_id,
+                target_title=target_title,
+                position=position,
+                move_contract="modern",
+            )
+            return self._coerce_dict(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() -> list[dict[str, Any]]:
+            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() -> list[dict[str, Any]]:
+            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() -> dict[str, Any]:
+            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 self._coerce_dict(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() -> dict[str, Any]:
+            result = self._client.history(page_id)  # type: ignore[attr-defined]
+            self._log.debug("page_history_retrieved", page_id=page_id)
+            return self._coerce_dict(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() -> dict[str, Any]:
+            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 self._coerce_dict(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 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() -> dict[str, Any]:
+            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() -> dict[str, Any]:
+            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 self._coerce_dict(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() -> dict[str, Any]:
+            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, expand: list[str] | None = None) -> list[dict[str, Any]]:
+        """Get child pages of a page.
+
+        Uses the official SDK `get_page_child_by_type()` when available so callers can:
+        - control pagination reliably
+        - request expanded fields (for example `body.storage`) in one round trip
+        """
+
+        def operation():
+            expand_arg = ",".join(expand) if expand else None
+
+            # `atlassian.Confluence.get_child_pages()` does not expose pagination controls.
+            # Prefer `get_page_child_by_type()` so crawlers don't silently miss children.
+            if hasattr(self._client, "get_page_child_by_type"):
+                start = 0
+                limit = 100
+                collected: list[dict[str, Any]] = []
+                seen_starts: set[int] = set()
+                seen_tokens: set[str] = set()
+                guard_reason: str | None = None
+
+                while True:
+                    if start in seen_starts:
+                        guard_reason = "repeated_start"
+                        break
+                    seen_starts.add(start)
+
+                    payload = self._client.get_page_child_by_type(
+                        page_id,
+                        type="page",
+                        start=start,
+                        limit=limit,
+                        expand=expand_arg,
+                    )
+                    results: list[dict[str, Any]] = []
+                    if isinstance(payload, dict):
+                        raw = payload.get("results", [])
+                        if isinstance(raw, list):
+                            results = [item for item in raw if isinstance(item, dict)]
+                    elif isinstance(payload, list):
+                        results = [item for item in payload if isinstance(item, dict)]
+                    else:
+                        results = []
+
+                    if not results:
+                        break
+
+                    collected.extend(results)
+
+                    next_start: int | None = None
+                    next_token: str | None = None
+                    if isinstance(payload, dict):
+                        next_start, next_token = self._extract_pagination_marker(payload)
+
+                    if next_token:
+                        if next_token in seen_tokens:
+                            guard_reason = "repeated_token"
+                            break
+                        seen_tokens.add(next_token)
+
+                    if next_start is not None:
+                        if next_start <= start:
+                            guard_reason = "no_progress_start"
+                            break
+                        start = next_start
+                        continue
+
+                    if len(results) < limit:
+                        break
+                    start += limit
+
+                if guard_reason:
+                    log_fn = self._log.info if guard_reason == "no_progress_start" else self._log.warning
+                    log_fn(
+                        "child_pages_pagination_guard_triggered",
+                        page_id=page_id,
+                        reason=guard_reason,
+                        count=len(collected),
+                        last_start=start,
+                    )
+
+                self._log.debug(
+                    "child_pages_retrieved",
+                    page_id=page_id,
+                    count=len(collected),
+                    expand=expand_arg,
+                )
+                return collected
+
+            result = self._client.get_child_pages(page_id)
+            # Convert generator to list if needed.
+            if result is not None and hasattr(result, "__iter__") and not isinstance(result, (list, tuple, dict)):
+                result = list(result)
+            result_list: list[dict[str, Any]] = []
+            if isinstance(result, list):
+                result_list = [item for item in result if isinstance(item, dict)]
+            self._log.debug(
+                "child_pages_retrieved",
+                page_id=page_id,
+                count=len(result_list),
+                expand=expand_arg,
+            )
+            return result_list
+
+        return self._with_retry(operation, 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)
+            if result is None:
+                return None
+            return self._require_dict(result, "get_page_by_title")
+
+        except Exception as exc:
+            self._handle_api_error(exc, f"get_page_by_title {space_key}/{title}")
+            raise
+
+    def get_attachments(self, page_id: str) -> list[dict[str, Any]]:
+        """Get attachments for a page."""
+        try:
+            start = 0
+            limit = 50
+            collected: list[dict[str, Any]] = []
+            seen_starts: set[int] = set()
+            seen_tokens: set[str] = set()
+            guard_reason: str | None = None
+
+            while True:
+                if start in seen_starts:
+                    guard_reason = "repeated_start"
+                    break
+                seen_starts.add(start)
+
+                payload = self._client.get_attachments_from_content(page_id, start=start, limit=limit)
+                results: list[dict[str, Any]] = []
+                if isinstance(payload, dict):
+                    raw = payload.get("results", [])
+                    if isinstance(raw, list):
+                        results = [item for item in raw if isinstance(item, dict)]
+                elif isinstance(payload, list):
+                    results = [item for item in payload if isinstance(item, dict)]
+                else:
+                    results = []
+
+                if not results:
+                    break
+
+                collected.extend(results)
+
+                next_start: int | None = None
+                next_token: str | None = None
+                if isinstance(payload, dict):
+                    next_start, next_token = self._extract_pagination_marker(payload)
+
+                if next_token:
+                    if next_token in seen_tokens:
+                        guard_reason = "repeated_token"
+                        break
+                    seen_tokens.add(next_token)
+
+                if next_start is not None:
+                    if next_start <= start:
+                        guard_reason = "no_progress_start"
+                        break
+                    start = next_start
+                    continue
+
+                if len(results) < limit:
+                    break
+                start += limit
+
+            if guard_reason:
+                log_fn = self._log.info if guard_reason == "no_progress_start" else self._log.warning
+                log_fn(
+                    "attachments_pagination_guard_triggered",
+                    page_id=page_id,
+                    reason=guard_reason,
+                    count=len(collected),
+                    last_start=start,
+                )
+
+            self._log.debug("attachments_retrieved", page_id=page_id, count=len(collected))
+            return collected
+
+        except Exception as exc:
+            self._handle_api_error(exc, f"get_attachments {page_id}")
+            raise
+
+    def get_attachment_content(self, attachment_id: str) -> bytes:
+        """Get attachment content by ID."""
+        try:
+            # Cloud SDKs expose `get_attachment_data`, but Server variants may not.
+            get_attachment_data = getattr(self._client, "get_attachment_data", None)
+            if callable(get_attachment_data):
+                result = get_attachment_data(attachment_id)
+                self._log.debug("attachment_content_retrieved", attachment_id=attachment_id, source="sdk")
+                return self._coerce_bytes(result)
+
+            # Fallback for Confluence Server: resolve the attachment metadata, then download via `_links.download`.
+            from urllib.parse import urlparse
+
+            def _raise_for_status(response: Any) -> None:
+                if hasattr(response, "raise_for_status"):
+                    response.raise_for_status()
+                    return
+                status_code = getattr(response, "status_code", None)
+                if isinstance(status_code, int) and status_code >= 400:
+                    raise ResponseError(
+                        f"Unexpected status {status_code}",
+                        status_code=status_code,
+                        context={"status_code": status_code},
+                    )
+
+            def _as_path(url_or_path: str) -> str:
+                if url_or_path.startswith(("http://", "https://")):
+                    parsed = urlparse(url_or_path)
+                    path = parsed.path or "/"
+                    if parsed.query:
+                        path = f"{path}?{parsed.query}"
+                    return path
+                return url_or_path if url_or_path.startswith("/") else f"/{url_or_path}"
+
+            meta_response = self.request(
+                "GET",
+                f"/rest/api/content/{attachment_id}",
+                params={"expand": "version"},
+            )
+            _raise_for_status(meta_response)
+            payload = meta_response.json()
+            download_link = None
+            if isinstance(payload, dict):
+                links = payload.get("_links")
+                if isinstance(links, dict):
+                    download_link = links.get("download")
+            if not download_link or not isinstance(download_link, str):
+                raise VDSClientError(
+                    "Attachment download link not found in response",
+                    context={"attachment_id": attachment_id},
+                )
+
+            download_response = self.request(
+                "GET",
+                _as_path(download_link),
+                headers={"Accept": "*/*"},
+            )
+            _raise_for_status(download_response)
+            content = getattr(download_response, "content", None)
+            if isinstance(content, bytes):
+                self._log.debug("attachment_content_retrieved", attachment_id=attachment_id, source="download_link")
+                return content
+            # Fallback: some clients expose bytes via `read()` or `text`.
+            if hasattr(download_response, "read"):
+                data = download_response.read()
+                if isinstance(data, bytes):
+                    self._log.debug(
+                        "attachment_content_retrieved", attachment_id=attachment_id, source="download_link_read"
+                    )
+                    return data
+            text = getattr(download_response, "text", "")
+            self._log.debug("attachment_content_retrieved", attachment_id=attachment_id, source="download_link_text")
+            return (text or "").encode("utf-8")
+
+        except Exception as exc:
+            self._handle_api_error(exc, f"get_attachment_content {attachment_id}")
+            raise
+
+    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() -> dict[str, Any]:
+            # 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 self._coerce_dict(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 VDSClientError(
+                    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, parent_id: str | None = None) -> dict[str, Any]:
+        """Add a comment to a page or reply to an existing comment.
+
+        When ``parent_id`` is provided, the comment will be created as a reply
+        to the specified parent comment (threaded reply), mirroring
+        :py:meth:`Confluence.add_comment` from the Atlassian SDK.
+        """
+
+        comment_params = set(self._safe_signature_params(self._client.add_comment))
+        supports_parent = "parent_id" in comment_params or len(comment_params) >= 4
+        if parent_id is not None and not supports_parent:
+            raise VDSClientError(
+                "Installed atlassian-python-api build does not support parent comment replies",
+                context={"page_id": page_id},
+            )
+
+        def _op() -> dict[str, Any]:
+            if parent_id is not None:
+                result = self._client.add_comment(page_id, body, parent_id)  # type: ignore[call-arg]
+            else:
+                result = self._client.add_comment(page_id, body)
+            self._log.info("comment_added", page_id=page_id, parent_id=parent_id)
+            return self._coerce_dict(result)
+
+        return self._with_retry(_op, "add_comment")
+
+    def get_page_history(self, page_id: str) -> dict[str, Any]:
+        """Get page version history."""
+        try:
+            history_method = getattr(self._client, "get_history", None)
+            if not callable(history_method):
+                history_method = getattr(self._client, "history", None)
+            if not callable(history_method):
+                raise VDSClientError("SDK does not support page history retrieval")
+            result = history_method(page_id)
+            self._log.debug("page_history_retrieved", page_id=page_id)
+            return self._coerce_dict(result)
+
+        except Exception as exc:
+            self._handle_api_error(exc, f"get_page_history {page_id}")
+            raise
+
+    @property
+    def base_url(self) -> str:
+        """Base URL of the Confluence server (no trailing slash)."""
+        return str(self._settings.url_for(self._server)).rstrip("/")
+
+    # --- Label Operations ---
+
+    def get_page_labels(self, page_id: str) -> list[dict[str, Any]]:
+        """Return raw label result list for a page."""
+
+        def operation() -> list[dict[str, Any]]:
+            method = getattr(self._client, "get_page_labels", None)
+            if not callable(method):
+                # Fallback: REST endpoint (older SDK versions)
+                resp = self._client.request("GET", f"rest/api/content/{page_id}/label")
+                payload = resp.json() if hasattr(resp, "json") else {}
+                return payload.get("results", []) if isinstance(payload, dict) else []
+            result = method(page_id)
+            if isinstance(result, dict):
+                return result.get("results", [])
+            return list(result) if result else []
+
+        return self._with_retry(operation, f"get_page_labels {page_id}")
+
+    def set_page_label(self, page_id: str, label: str) -> None:
+        """Add a label to a page."""
+
+        def operation() -> None:
+            method = getattr(self._client, "set_page_label", None)
+            if not callable(method):
+                # Fallback: REST endpoint (older SDK versions)
+                self._client.request(
+                    "POST",
+                    f"rest/api/content/{page_id}/label",
+                    data=[{"prefix": "global", "name": label}],
+                )
+                return
+            method(page_id, label)
+
+        return self._with_retry(operation, f"set_page_label {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"]