Struct ConfluenceApi 

pub struct ConfluenceApi { /* private fields */ }

Confluence Cloud REST API v2 backend.

Implementations

impl ConfluenceApi

pub fn new(client: AtlassianClient) -> Self

Creates a new Confluence API backend.

impl ConfluenceApi

pub async fn resolve_space_id(&self, space_key: &str) -> Result<String>

Resolves a space key to a space ID via the Confluence API.

pub async fn list_spaces( &self, keys: &[&str], type_: Option<&str>, status: Option<&str>, cursor: Option<&str>, limit: u32, ) -> Result<ConfluenceSpacePage>

Lists Confluence spaces (one page at a time).

Optional filters: keys (matches any of the given space keys; joined as a single comma-separated query parameter), type (one of "global", "personal", "collaboration", "knowledge_base"), status (one of "current", "archived"). Pagination is not auto-drained: pass ConfluenceSpacePage::next_cursor back as cursor to fetch the next page.

pub async fn list_space_pages( &self, space_id: &str, status: Option<&str>, sort: Option<&str>, cursor: Option<&str>, limit: u32, ) -> Result<PageSummaryPage>

Enumerates pages within a Confluence space (one response at a time).

Optional filters are passed through to the Confluence v2 API verbatim: status (e.g. current, archived, draft, trashed) and sort (e.g. id, -id, title, -title, created-date, -created-date, modified-date, -modified-date). Pagination is not auto-drained: pass PageSummaryPage::next_cursor back as cursor to fetch the next page.

pub async fn create_page( &self, space_key: &str, title: &str, body_adf: &ValidatedAdfDocument, parent_id: Option<&str>, ) -> Result<String>

Creates a new Confluence page.

pub async fn move_page( &self, page_id: &str, target_id: &str, position: MovePosition, ) -> Result<MovedPage>

Moves or reparents a Confluence page within its current space.

Same-space only — cross-space moves are not supported by the v2 API. Uses the v1 move endpoint (PUT /wiki/rest/api/content/{id}/move/{position}/{target}), then re-fetches the page with ?include-ancestors=true to populate the returned MovedPage.

pub async fn copy_page( &self, page_id: &str, dest_parent_id: &str, new_title: &str, ) -> Result<String>

Copies a single Confluence page under a destination parent page.

Uses the v1 copy endpoint (POST /wiki/rest/api/content/{id}/copy), carrying the page’s attachments, labels, and properties (but not its restrictions). Returns the new page’s id. Single-page copy only — the hierarchy-copy endpoint is a separate async task not handled here.

pub async fn is_watching_content( &self, content_id: &str, account_id: Option<&str>, ) -> Result<ConfluenceWatchStatus>

Reports whether a user is watching a Confluence page (the authenticated user when account_id is None).

GET /wiki/rest/api/user/watch/content/{id}.

pub async fn add_content_watcher( &self, content_id: &str, account_id: Option<&str>, ) -> Result<()>

Adds a watcher to a Confluence page (the authenticated user when account_id is None).

POST /wiki/rest/api/user/watch/content/{id}.

pub async fn remove_content_watcher( &self, content_id: &str, account_id: Option<&str>, ) -> Result<()>

Removes a watcher from a Confluence page (the authenticated user when account_id is None).

DELETE /wiki/rest/api/user/watch/content/{id}.

pub async fn get_content_restrictions(&self, content_id: &str) -> Result<Value>

Reads the read/update restrictions on a Confluence page.

GET /wiki/rest/api/content/{id}/restriction. Returns the raw response JSON (the restriction model is deeply nested — user/group arrays per operation — so it is surfaced verbatim rather than reshaped).

pub async fn grant_content_restriction( &self, content_id: &str, operation: &str, account_id: Option<&str>, group: Option<&str>, ) -> Result<()>

Grants a user or group a restriction for an operation (read/update) on a Confluence page.

PUT /wiki/rest/api/content/{id}/restriction/byOperation/{op}/{user|group}/….

pub async fn revoke_content_restriction( &self, content_id: &str, operation: &str, account_id: Option<&str>, group: Option<&str>, ) -> Result<()>

Revokes a user’s or group’s restriction for an operation on a page.

DELETE /wiki/rest/api/content/{id}/restriction/byOperation/{op}/{user|group}/….

pub async fn delete_page(&self, id: &str, purge: bool) -> Result<()>

Deletes a Confluence page.

pub async fn get_children(&self, page_id: &str) -> Result<Vec<ChildPage>>

Fetches all child pages of a given page, handling pagination.

Uses the v1 content API (/wiki/rest/api/content/{id}/child/page) which is more widely supported than the v2 children endpoint.

pub async fn get_space_root_pages( &self, space_id: &str, ) -> Result<Vec<ChildPage>>

Fetches top-level pages in a space (pages with no parent), handling pagination.

Uses the v2 API endpoint /wiki/api/v2/spaces/{space-id}/pages?depth=root.

pub async fn get_page_comments( &self, page_id: &str, ) -> Result<Vec<ConfluenceComment>>

Lists footer comments on a Confluence page, handling pagination.

pub async fn get_page_inline_comments( &self, page_id: &str, ) -> Result<Vec<ConfluenceComment>>

Lists inline comments on a Confluence page, handling pagination.

pub async fn get_comment_replies( &self, comment_id: &str, kind: CommentKind, ) -> Result<Vec<ConfluenceComment>>

Lists the replies (child comments) of a comment.

kind selects which Confluence v2 endpoint to hit: footer replies and inline replies live on separate URLs. The returned comments are stamped with the same kind as the parent — Confluence treats reply chains as homogenous.

pub async fn add_page_comment( &self, page_id: &str, body_adf: &ValidatedAdfDocument, ) -> Result<()>

Adds a footer comment to a Confluence page.

pub async fn add_inline_page_comment( &self, page_id: &str, body_adf: &ValidatedAdfDocument, anchor: &InlineAnchor, ) -> Result<()>

Adds an inline comment anchored to a text selection on a Confluence page.

anchor is typically produced by Self::resolve_anchor, which counts occurrences on the live page and validates that a 1-based match_index the user supplied is in range.

pub async fn update_page_comment( &self, comment_id: &str, kind: CommentKind, body_adf: &ValidatedAdfDocument, ) -> Result<()>

Edits an existing footer or inline comment’s body.

PUT /wiki/api/v2/{segment}/{id}. Confluence versions comments, so the current version is fetched first and the update sends version.number + 1 alongside the new ADF body.

pub async fn delete_page_comment( &self, comment_id: &str, kind: CommentKind, ) -> Result<()>

Deletes a footer or inline comment from a Confluence page.

DELETE /wiki/api/v2/{segment}/{id}.

pub async fn set_inline_comment_resolved( &self, comment_id: &str, resolved: bool, ) -> Result<()>

Resolves (resolved = true) or reopens (resolved = false) an inline comment.

PUT /wiki/api/v2/inline-comments/{id} carrying the resolved flag. The v2 update contract requires version and body, so the current version and body are fetched first and re-sent unchanged with the toggled flag. Footer comments have no resolution state, so this is inline-only.

pub async fn resolve_anchor( &self, page_id: &str, anchor_text: &str, match_index_1based: Option<usize>, ) -> Result<InlineAnchor>

Resolves an inline-comment anchor by counting anchor_text occurrences in the live page body.

match_index_1based is what the user typed (1-based) and is None if they omitted the flag. The returned InlineAnchor is ready to hand to Self::add_inline_page_comment.

Errors

• The anchor text does not appear on the page.
• The text appears more than once and no --match-index was supplied.
• The supplied --match-index is outside 1..=match_count.

pub async fn get_labels(&self, page_id: &str) -> Result<Vec<ConfluenceLabel>>

Fetches all labels on a Confluence page, handling pagination.

pub async fn add_labels(&self, page_id: &str, labels: &[String]) -> Result<()>

Adds one or more labels to a Confluence page.

pub async fn remove_label(&self, page_id: &str, label_name: &str) -> Result<()>

Removes a label from a Confluence page.

pub async fn get_page_metadata(&self, page_id: &str) -> Result<PageMetadata>

Fetches lightweight metadata (id, title, current version) for a page.

Cheaper than AtlassianApi::get_content because it skips the body and the space-key lookup.

pub async fn list_page_versions( &self, page_id: &str, since: Option<&SinceFilter>, limit: u32, ) -> Result<(Vec<PageVersion>, bool)>

Lists version history for a Confluence page, auto-paginated.

Returns up to limit versions matching the optional since filter. limit = 0 means unlimited. The Confluence v2 API returns versions newest-first, so encountering a version older than since ends pagination early.

The boolean in the return tuple is truncated: true when limit was hit before the API was exhausted (more newer-than-since versions exist upstream).

pub async fn upload_attachment( &self, page_id: &str, file_path: &Path, filename: Option<&str>, comment: Option<&str>, minor_edit: bool, ) -> Result<ConfluenceAttachment>

Uploads an attachment to a Confluence page from a local file path.

Streams the file body — the file is never fully buffered in memory. Sends X-Atlassian-Token: no-check (Atlassian convention for state-changing multipart endpoints).

Does not retry on 429: see AtlassianClient::post_multipart.

pub async fn update_attachment( &self, page_id: &str, attachment_id: &str, file_path: &Path, filename: Option<&str>, comment: Option<&str>, minor_edit: bool, ) -> Result<ConfluenceAttachment>

Uploads a new binary version of an existing attachment, bumping its version rather than creating a second attachment.

Mirrors Self::upload_attachment’s multipart machinery but targets the per-attachment .../child/attachment/{attachmentId}/data endpoint (v1 only, like attachment creation — the v2 API has no attachment-mutation endpoint). Returns the updated attachment metadata.

pub async fn list_attachments( &self, page_id: &str, cursor: Option<&str>, limit: u32, ) -> Result<ConfluenceAttachmentPage>

Lists attachments on a Confluence page (one page at a time).

Unlike other v2 list helpers in this module, this does not auto-drain pagination: pass ConfluenceAttachmentPage::next_cursor back as cursor to fetch the next page.

pub async fn delete_attachment( &self, attachment_id: &str, purge: bool, ) -> Result<()>

Deletes an attachment by ID.

When purge is true, permanently purges (requires space admin); otherwise the attachment is moved to trash.

pub async fn get_attachment( &self, attachment_id: &str, ) -> Result<ConfluenceAttachment>

Fetches metadata for a single attachment by ID (v2 API).

Returns the same ConfluenceAttachment shape as ConfluenceApi::list_attachments, including the download_url needed by ConfluenceApi::download_attachment_bytes.

pub async fn download_attachment_bytes( &self, attachment: &ConfluenceAttachment, ) -> Result<Vec<u8>>

Downloads the binary content of an attachment whose metadata is already in hand (e.g. from ConfluenceApi::list_attachments).

The v1/v2 APIs report download_url as a path relative to the Confluence context root; it is resolved against the instance URL and fetched via the shared client, which follows the media-CDN redirect.

pub async fn download_attachment( &self, attachment_id: &str, ) -> Result<(ConfluenceAttachment, Vec<u8>)>

Fetches an attachment’s metadata by ID, then downloads its binary.

Convenience for the single-attachment download path (CLI/MCP) where only the ID is known; the fan-out path uses ConfluenceApi::download_attachment_bytes directly to avoid an extra metadata round-trip per attachment.

pub async fn get_page_at_version( &self, id: &str, version: u32, ) -> Result<ContentItem>

Fetches a Confluence page pinned to a specific version number.

Like AtlassianApi::get_content but returns the historical snapshot at version rather than the current head. Used by the version-comparison tooling to fetch each side of the diff independently — Confluence stores versions as immutable snapshots.

Trait Implementations

impl AtlassianApi for ConfluenceApi

fn get_content<'a>( &'a self, id: &'a str, ) -> Pin<Box<dyn Future<Output = Result<ContentItem>> + Send + 'a>>

Fetches a content item by its identifier.

fn update_content<'a>( &'a self, id: &'a str, body_adf: &'a ValidatedAdfDocument, title: Option<&'a str>, ) -> Pin<Box<dyn Future<Output = Result<()>> + Send + 'a>>

Updates a content item’s body and optionally its title.

fn verify_auth<'a>( &'a self, ) -> Pin<Box<dyn Future<Output = Result<String>> + Send + 'a>>

Verifies authentication and returns a display name.

fn backend_name(&self) -> &'static str

Returns the backend type name (“jira” or “confluence”).