Confluence: fix cursor and add method of admin related level

Author: gonchik

atlassian/confluence/base.py

@@ -2,7 +2,7 @@
 
 import copy
 import re
-from urllib.parse import urljoin, urlparse
+from urllib.parse import parse_qsl, urljoin, urlparse
 import logging
 from requests import HTTPError
 from ..rest_client import AtlassianRestAPI
@@ -167,6 +167,7 @@ def _get_paged(
             params = {}
 
         while True:
+            current_url = url
             response = self.get(
                 url,
                 trailing=trailing,
@@ -190,6 +191,16 @@ def _get_paged(
             if url is None:
                 break
 
+            # Cloud V2 cursor links contain a relative endpoint and a cursor
+            # query.  Reusing the already-resolved endpoint preserves both
+            # ``/wiki`` and API-gateway tenant prefixes.
+            parsed_next = urlparse(url)
+            if getattr(self, "api_version", None) == 2 and parsed_next.query and not parsed_next.scheme:
+                url = current_url
+                params = dict(parse_qsl(parsed_next.query, keep_blank_values=True))
+                trailing = False
+                continue
+
             if not urlparse(url).scheme:
                 # Confluence returns both ``/rest/api/...`` and
                 # ``rest/api/...`` forms for next links.  Neither is an

atlassian/confluence/cloud/admin_management.py

@@ -0,0 +1,125 @@
+"""Confluence Cloud v2 administrative and workspace operations."""
+
+
+class AdminManagementOperations:
+    """Wrappers for v2 administrative resources not covered by legacy helpers."""
+
+    @staticmethod
+    def _query(**values):
+        return {key: value for key, value in values.items() if value is not None}
+
+    def _v2(self, path):
+        return self.url_joiner("api/v2", path)
+
+    def get_admin_key(self):
+        return self.get(self._v2("admin-key"))
+
+    def enable_admin_key(self):
+        return self.post(self._v2("admin-key"))
+
+    def disable_admin_key(self):
+        return self.delete(self._v2("admin-key"))
+
+    def get_space_permissions(self, cursor=None, limit=None):
+        return self.get(self._v2("space-permissions"), params=self._query(cursor=cursor, limit=limit))
+
+    def get_space_permission_combinations(self, cursor=None, limit=None):
+        return self.get(
+            self._v2("space-permissions/transition/combinations"),
+            params=self._query(cursor=cursor, limit=limit),
+        )
+
+    def generate_space_permission_combinations(self, data=None):
+        return self.post(self._v2("space-permissions/transition/combinations"), data=data)
+
+    def assign_space_permission_roles(self, data=None):
+        return self.post(self._v2("space-permissions/transition/role-assignments"), data=data)
+
+    def remove_space_permission_access(self, data=None):
+        return self.post(self._v2("space-permissions/transition/access-removals"), data=data)
+
+    def get_space_permission_transition_task(self, task_id):
+        return self.get(self._v2(f"space-permissions/transition/tasks/{task_id}"))
+
+    def get_space_roles(
+        self,
+        space_id=None,
+        role_type=None,
+        principal_id=None,
+        principal_type=None,
+        cursor=None,
+        limit=None,
+    ):
+        return self.get(
+            self._v2("space-roles"),
+            params=self._query(
+                **{
+                    "space-id": space_id,
+                    "role-type": role_type,
+                    "principal-id": principal_id,
+                    "principal-type": principal_type,
+                    "cursor": cursor,
+                    "limit": limit,
+                }
+            ),
+        )
+
+    def create_space_role(self, data=None):
+        return self.post(self._v2("space-roles"), data=data)
+
+    def get_space_role(self, role_id):
+        return self.get(self._v2(f"space-roles/{role_id}"))
+
+    def update_space_role(self, role_id, data=None):
+        return self.put(self._v2(f"space-roles/{role_id}"), data=data)
+
+    def delete_space_role(self, role_id):
+        return self.delete(self._v2(f"space-roles/{role_id}"))
+
+    def get_space_role_mode(self):
+        return self.get(self._v2("space-role-mode"))
+
+    def bulk_get_users(self, data=None):
+        return self.post(self._v2("users-bulk"), data=data)
+
+    def check_user_access_by_email(self, data=None):
+        return self.post(self._v2("user/access/check-access-by-email"), data=data)
+
+    def invite_user_by_email(self, data=None):
+        return self.post(self._v2("user/access/invite-by-email"), data=data)
+
+    def get_data_policy_metadata(self):
+        return self.get(self._v2("data-policies/metadata"))
+
+    def get_data_policy_spaces(self, **filters):
+        return self.get(self._v2("data-policies/spaces"), params=self._query(**filters))
+
+    def get_global_footer_comments(self, **params):
+        return self.get(self._v2("footer-comments"), params=self._query(**params))
+
+    def create_global_footer_comment(self, data=None):
+        return self.post(self._v2("footer-comments"), data=data)
+
+    def get_global_inline_comments(self, **params):
+        return self.get(self._v2("inline-comments"), params=self._query(**params))
+
+    def create_global_inline_comment(self, data=None):
+        return self.post(self._v2("inline-comments"), data=data)
+
+    def get_comment_children_v2(self, comment_id, comment_type="footer-comments", **params):
+        return self.get(self._v2(f"{comment_type}/{comment_id}/children"), params=self._query(**params))
+
+    def get_comment_likes_count_v2(self, comment_id, comment_type="footer-comments"):
+        return self.get(self._v2(f"{comment_type}/{comment_id}/likes/count"))
+
+    def get_comment_likes_users_v2(self, comment_id, comment_type="footer-comments", **params):
+        return self.get(self._v2(f"{comment_type}/{comment_id}/likes/users"), params=self._query(**params))
+
+    def get_comment_operations_v2(self, comment_id, comment_type="footer-comments"):
+        return self.get(self._v2(f"{comment_type}/{comment_id}/operations"))
+
+    def get_comment_versions_v2(self, comment_id, comment_type="footer-comments", **params):
+        return self.get(self._v2(f"{comment_type}/{comment_id}/versions"), params=self._query(**params))
+
+    def get_comment_version_v2(self, comment_id, version_number, comment_type="footer-comments"):
+        return self.get(self._v2(f"{comment_type}/{comment_id}/versions/{version_number}"))

atlassian/confluence/cloud/cloud.py

@@ -18,6 +18,7 @@
 from .graphql import GraphQLOperations
 from .tasks import TaskOperations
 from .whiteboards import WhiteboardOperations
+from .admin_management import AdminManagementOperations
 
 log = logging.getLogger(__name__)
 
@@ -30,6 +31,7 @@ class ConfluenceCloud(
     TaskOperations,
     FolderOperations,
     DatabaseOperations,
+    AdminManagementOperations,
 ):
     """
     Confluence Cloud API implementation class

atlassian/confluence_base.py

@@ -4,7 +4,7 @@
 
 import logging
 from typing import Dict, List, Optional, Union
-from urllib.parse import urlparse
+from urllib.parse import parse_qsl, urlparse
 
 from atlassian.rest_client import AtlassianRestAPI
 
@@ -259,21 +259,32 @@ def _get_paged(
                 if not next_url:
                     break
 
-                # Use the next URL directly
-                # Check if the response has a base URL provided (common in Confluence v2 API)
-                base_url = response.get("_links", {}).get("base")
-                if base_url and next_url.startswith("/"):
-                    # Construct the full URL using the base URL from the response
-                    url = f"{base_url}{next_url}"
+                if isinstance(next_url, dict):
+                    next_url = next_url.get("href")
+                if not next_url:
+                    break
+
+                # Cursor links are commonly relative and include the endpoint
+                # path (for example ``/wiki/api/v2/spaces?cursor=...``).  The
+                # endpoint used for the first request is already resolved
+                # against the tenant or API-gateway context, so rebuilding it
+                # from ``_links.base`` can duplicate ``/wiki`` or drop an
+                # ``/ex/confluence/{cloud_id}`` prefix.  Keep the resolved
+                # endpoint and advance only its query parameters.
+                parsed_next = urlparse(next_url)
+                if parsed_next.scheme:
+                    url = next_url
                     absolute = True
+                    params = {}
+                elif parsed_next.query:
+                    params = dict(parse_qsl(parsed_next.query, keep_blank_values=True))
                 else:
+                    # A relative link without a query is unusual for cursor
+                    # pagination; retain the previous behavior as a safe
+                    # fallback for such responses.
                     url = next_url
-                    # Check if the URL is absolute (has http:// or https://) or contains the server's domain
-                    if next_url.startswith(("http://", "https://")) or self.url.split("/")[2] in next_url:
-                        absolute = True
-                    else:
-                        absolute = False
-                params = {}
+                    absolute = False
+                    params = {}
                 trailing = False
 
         return

docs/confluence.rst

@@ -1082,6 +1082,24 @@ trash. A folder may have a page or another folder as its parent. Use
 Scoped tokens require the corresponding ``write:folder:confluence``,
 ``read:folder:confluence``, or ``delete:folder:confluence`` scope.
 
+Additional Cloud v2 resources
+-----------------------------
+
+The Cloud v2 client also exposes administrative and workspace operations from
+the current OpenAPI contract:
+
+.. code-block:: python
+
+    admin_key = confluence.get_admin_key()
+    permissions = confluence.get_space_permissions(limit=25)
+    roles = confluence.get_space_roles(space_id="<space-id>", limit=25)
+    users = confluence.bulk_get_users({"accountIds": ["<account-id>"]})
+    policies = confluence.get_data_policy_spaces(ids=["<space-id>"])
+
+Global comments are available through ``get_global_footer_comments`` and
+``get_global_inline_comments``. Their child, likes, operations, and version
+resources are exposed by the corresponding ``*_v2`` helpers.
+
 Cloud group members
 -------------------
 

tests/test_confluence_cloud_admin_management.py

@@ -0,0 +1,26 @@
+from unittest.mock import patch
+
+from atlassian.confluence.cloud.cloud import ConfluenceCloud
+
+
+def test_admin_key_and_space_role_operations_use_v2_routes():
+    client = ConfluenceCloud("https://example.atlassian.net")
+    with patch.object(client, "get", return_value={}) as get:
+        client.get_admin_key()
+        client.get_space_roles(space_id="S1", limit=10)
+    assert get.call_args_list[0].args == ("api/v2/admin-key",)
+    assert get.call_args_list[1].args == ("api/v2/space-roles",)
+    assert get.call_args_list[1].kwargs["params"] == {"space-id": "S1", "limit": 10}
+
+
+def test_global_comment_and_data_policy_operations():
+    client = ConfluenceCloud("https://example.atlassian.net")
+    with patch.object(client, "post", return_value={}) as post:
+        client.create_global_footer_comment({"body": {}})
+        client.bulk_get_users({"accountIds": ["A1"]})
+    assert post.call_args_list[0].args == ("api/v2/footer-comments",)
+    assert post.call_args_list[1].args == ("api/v2/users-bulk",)
+
+    with patch.object(client, "get", return_value={}) as get:
+        client.get_data_policy_spaces(ids=["S1"], limit=10)
+    get.assert_called_once_with("api/v2/data-policies/spaces", params={"ids": ["S1"], "limit": 10})

tests/test_confluence_cloud_cursor_context.py

@@ -0,0 +1,35 @@
+from unittest.mock import patch
+
+from atlassian import ConfluenceV2
+
+
+def test_cloud_v2_cursor_preserves_wiki_context():
+    client = ConfluenceV2("https://example.atlassian.net")
+    responses = [
+        {
+            "results": [{"id": "1"}],
+            "_links": {"next": "/wiki/api/v2/spaces?limit=1&cursor=CURSOR"},
+        },
+        {"results": []},
+    ]
+    with patch.object(client, "get", side_effect=responses) as get:
+        assert list(client._get_paged("api/v2/spaces", params={"limit": 1})) == [{"id": "1"}]
+
+    assert get.call_args_list[1].args[0] == "api/v2/spaces"
+    assert get.call_args_list[1].kwargs["params"] == {"limit": "1", "cursor": "CURSOR"}
+
+
+def test_cloud_v2_cursor_preserves_gateway_context():
+    client = ConfluenceV2("https://api.atlassian.com/ex/confluence/CLOUD-ID")
+    responses = [
+        {
+            "results": [{"id": "1"}],
+            "_links": {"next": "/wiki/api/v2/spaces?limit=1&cursor=CURSOR"},
+        },
+        {"results": []},
+    ]
+    with patch.object(client, "get", side_effect=responses) as get:
+        list(client._get_paged("api/v2/spaces", params={"limit": 1}))
+
+    assert get.call_args_list[1].args[0] == "api/v2/spaces"
+    assert get.call_args_list[1].kwargs["params"] == {"limit": "1", "cursor": "CURSOR"}

tests/test_confluence_cursor_pagination.py

@@ -0,0 +1,41 @@
+from unittest.mock import patch
+
+from atlassian.confluence_base import ConfluenceBase
+
+
+def test_v2_relative_cursor_preserves_tenant_context_path():
+    client = ConfluenceBase("https://example.atlassian.net", api_version=2)
+    responses = [
+        {
+            "results": [{"id": "1"}],
+            "_links": {
+                "base": "https://example.atlassian.net/wiki",
+                "next": "/wiki/api/v2/spaces?limit=1&cursor=CURSOR",
+            },
+        },
+        {"results": []},
+    ]
+    with patch.object(client, "get", side_effect=responses) as get:
+        assert list(client._get_paged("api/v2/spaces", params={"limit": 1})) == [{"id": "1"}]
+
+    assert get.call_args_list[1].args[0] == "api/v2/spaces"
+    assert get.call_args_list[1].kwargs["params"] == {"limit": "1", "cursor": "CURSOR"}
+
+
+def test_v2_relative_cursor_preserves_api_gateway_prefix():
+    client = ConfluenceBase("https://api.atlassian.com/ex/confluence/CLOUD-ID", api_version=2)
+    responses = [
+        {
+            "results": [{"id": "1"}],
+            "_links": {
+                "base": "https://example.atlassian.net/wiki",
+                "next": "/wiki/api/v2/spaces?limit=1&cursor=CURSOR",
+            },
+        },
+        {"results": []},
+    ]
+    with patch.object(client, "get", side_effect=responses) as get:
+        list(client._get_paged("api/v2/spaces", params={"limit": 1}))
+
+    assert get.call_args_list[1].args[0] == "api/v2/spaces"
+    assert get.call_args_list[1].kwargs["params"] == {"limit": "1", "cursor": "CURSOR"}