Struct AtlassianClient 

pub struct AtlassianClient { /* private fields */ }

Shared HTTP client for Atlassian Cloud REST APIs.

Backs every JIRA, Confluence, and Agile helper exposed by this crate. Construct directly via AtlassianClient::new (instance URL + email + API token) or, more commonly, via AtlassianClient::from_credentials which accepts an AtlassianCredentials resolved from the ATLASSIAN_INSTANCE_URL, ATLASSIAN_EMAIL, and ATLASSIAN_API_TOKEN environment variables (falling back to ~/.omni-dev/settings.json) by load_credentials.

Authenticates every request with HTTP Basic auth: a precomputed Authorization: Basic <base64(email:api_token)> header is attached to all outbound calls. Requests time out after 30s and automatically retry up to three times on HTTP 429, honoring any Retry-After header.

Implementations

impl AtlassianClient

pub fn new(instance_url: &str, email: &str, api_token: &str) -> Result<Self>

Creates a new Atlassian API client.

Constructs the Basic Auth header from the email and API token.

pub fn from_credentials(creds: &AtlassianCredentials) -> Result<Self>

Creates a client from stored credentials.

pub fn instance_url(&self) -> &str

Returns the instance URL.

pub async fn get_json(&self, url: &str) -> Result<Response>

Sends an authenticated GET request and returns the raw response.

Shared transport method used by both JIRA and Confluence API implementations.

pub async fn put_json<T: Serialize + Sync + ?Sized>( &self, url: &str, body: &T, ) -> Result<Response>

Sends an authenticated PUT request with a JSON body and returns the raw response.

Shared transport method used by both JIRA and Confluence API implementations.

pub async fn post_json<T: Serialize + Sync + ?Sized>( &self, url: &str, body: &T, ) -> Result<Response>

Sends an authenticated POST request with a JSON body and returns the raw response.

pub async fn get_bytes(&self, url: &str) -> Result<Vec<u8>>

Sends an authenticated GET request and returns raw bytes.

pub async fn delete(&self, url: &str) -> Result<Response>

Sends an authenticated DELETE request and returns the raw response.

pub async fn post_multipart( &self, url: &str, form: Form, extra_headers: &[(&str, &str)], ) -> Result<Response>

Sends an authenticated POST request with a multipart body and returns the raw response.

Does not retry on 429: a streamed multipart body cannot be replayed. Callers that need retry must rebuild the form and call again.

pub async fn get_issue(&self, key: &str) -> Result<JiraIssue>

Fetches a JIRA issue by key with only the standard fields.

Thin shim over Self::get_issue_with_fields with FieldSelection::Standard. Preserved for callers that do not need custom field data.

pub async fn get_issue_with_fields( &self, key: &str, selection: FieldSelection, ) -> Result<JiraIssue>

Fetches a JIRA issue by key with the given field selection.

Always requests expand=names,schema so human-readable field names and type metadata are available for rendering custom fields. When selection is FieldSelection::Standard, custom_fields on the returned issue will be empty.

pub async fn update_issue( &self, key: &str, description_adf: &ValidatedAdfDocument, summary: Option<&str>, ) -> Result<()>

Updates a JIRA issue’s description and optionally its summary.

Thin shim over Self::update_issue_with_custom_fields that sends no custom field changes.

pub async fn update_issue_with_custom_fields( &self, key: &str, description_adf: Option<&ValidatedAdfDocument>, summary: Option<&str>, parent: Option<&str>, custom_fields: &BTreeMap<String, Value>, ) -> Result<()>

Updates a JIRA issue with any subset of supported fields.

description_adf, summary, and parent are each Option: None leaves the field untouched, Some overwrites it. custom_fields is merged verbatim into the fields payload, keyed by stable JIRA field id — both standard fields (assignee, reporter, priority, labels) and custom fields (customfield_19300). Returns an error when nothing would be sent (avoids a no-op PUT that JIRA still validates).

pub async fn get_editmeta(&self, key: &str) -> Result<EditMeta>

Fetches editable field metadata scoped to an issue’s edit screen.

GET /rest/api/3/issue/{key}/editmeta returns only fields on the issue’s screen, so field names are unambiguous even when multiple custom fields share a display name globally.

pub async fn create_issue( &self, project_key: &str, issue_type: &str, summary: &str, description_adf: Option<&ValidatedAdfDocument>, labels: &[String], ) -> Result<JiraCreatedIssue>

Creates a new JIRA issue.

Thin shim over Self::create_issue_with_custom_fields that sends no custom field values.

pub async fn create_issue_with_custom_fields( &self, project_key: &str, issue_type: &str, summary: &str, description_adf: Option<&ValidatedAdfDocument>, labels: &[String], custom_fields: &BTreeMap<String, Value>, ) -> Result<JiraCreatedIssue>

Creates a new JIRA issue with standard fields and any custom fields keyed by stable ID (e.g., customfield_19300).

pub async fn get_createmeta( &self, project_key: &str, issue_type: &str, ) -> Result<EditMeta>

Fetches field metadata for creating a JIRA issue of a given project and issue type.

GET /rest/api/3/issue/createmeta?projectKeys={p}&issuetypeNames={t}&expand=projects.issuetypes.fields returns fields on the create screen, which is the write-time source of truth for custom-field resolution prior to issue creation.

pub async fn get_comments( &self, key: &str, limit: u32, ) -> Result<Vec<JiraComment>>

Lists comments on a JIRA issue with auto-pagination.

limit caps the total number of comments returned. Pass 0 for unlimited.

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

Adds a comment to a JIRA issue.

pub async fn update_comment( &self, key: &str, comment_id: &str, body_adf: &ValidatedAdfDocument, visibility: Option<&JiraVisibility>, ) -> Result<JiraComment>

Updates an existing comment on a JIRA issue.

Issues a PUT /rest/api/3/issue/{key}/comment/{id} with the new ADF body and an optional visibility restriction. Returns the updated comment as parsed from the JIRA response so callers can surface the updated timestamp and any author/body changes JIRA applied.

pub async fn get_worklogs( &self, key: &str, limit: u32, ) -> Result<JiraWorklogList>

Lists worklogs for a JIRA issue.

pub async fn add_worklog( &self, key: &str, time_spent: &str, started: Option<&str>, comment: Option<&str>, ) -> Result<()>

Adds a worklog entry to a JIRA issue.

pub async fn get_transitions(&self, key: &str) -> Result<Vec<JiraTransition>>

Lists available transitions for a JIRA issue.

pub async fn do_transition(&self, key: &str, transition_id: &str) -> Result<()>

Executes a transition on a JIRA issue.

pub async fn search_issues( &self, jql: &str, limit: u32, ) -> Result<JiraSearchResult>

Searches JIRA issues using JQL with auto-pagination.

limit controls total results: 0 means unlimited.

pub async fn search_confluence( &self, cql: &str, limit: u32, ) -> Result<ConfluenceSearchResults>

Searches Confluence pages using CQL with auto-pagination.

pub async fn search_jira_users( &self, query: &str, limit: u32, ) -> Result<JiraUserSearchResults>

Searches JIRA users by display name or email substring.

query is matched against displayName and emailAddress server- side; matching is substring and case-insensitive. limit of 0 returns every match (paginating internally), otherwise the result is truncated. Inactive users and app/customer account types are included — callers that need only assignable atlassian-account users should filter on active and account_type.

Note: many tenants strip emailAddress from search results due to GDPR / privacy settings, even when the user has an email on file.

pub async fn search_confluence_users( &self, query: &str, limit: u32, ) -> Result<ConfluenceUserSearchResults>

Searches Confluence users by display name or email.

pub async fn get_boards( &self, project: Option<&str>, board_type: Option<&str>, limit: u32, ) -> Result<AgileBoardList>

Lists agile boards with auto-pagination.

pub async fn get_board_issues( &self, board_id: u64, jql: Option<&str>, limit: u32, ) -> Result<JiraSearchResult>

Lists issues on an agile board with auto-pagination.

pub async fn get_sprints( &self, board_id: u64, state: Option<&str>, limit: u32, ) -> Result<AgileSprintList>

Lists sprints for an agile board with auto-pagination.

pub async fn get_sprint_issues( &self, sprint_id: u64, jql: Option<&str>, limit: u32, ) -> Result<JiraSearchResult>

Lists issues in an agile sprint with auto-pagination.

pub async fn add_issues_to_sprint( &self, sprint_id: u64, issue_keys: &[&str], ) -> Result<()>

Adds issues to an agile sprint.

pub async fn create_sprint( &self, board_id: u64, name: &str, start_date: Option<&str>, end_date: Option<&str>, goal: Option<&str>, ) -> Result<AgileSprint>

Creates a new sprint on an agile board.

pub async fn update_sprint( &self, sprint_id: u64, name: Option<&str>, state: Option<&str>, start_date: Option<&str>, end_date: Option<&str>, goal: Option<&str>, ) -> Result<()>

Updates an existing sprint.

pub async fn get_project_versions( &self, project_key: &str, released: Option<bool>, archived: Option<bool>, ) -> Result<JiraProjectVersionList>

Lists versions for a JIRA project.

Uses the lightweight GET /rest/api/3/project/{key}/versions endpoint, which returns all versions in a single response without pagination. released and archived filters are applied client-side.

pub async fn create_project_version( &self, project_key: &str, name: &str, description: Option<&str>, release_date: Option<&str>, start_date: Option<&str>, released: bool, archived: bool, ) -> Result<JiraProjectVersion>

Creates a new version in a JIRA project.

Validates release_date and start_date as YYYY-MM-DD client-side to surface clear errors before JIRA rejects the request with an opaque 400.

pub async fn get_issue_links(&self, key: &str) -> Result<Vec<JiraIssueLink>>

Lists links on a JIRA issue.

pub async fn get_remote_issue_links( &self, key: &str, ) -> Result<Vec<JiraRemoteIssueLink>>

Lists remote (external URL) issue links on a JIRA issue.

Endpoint: GET /rest/api/3/issue/{key}/remotelink — returns a bare JSON array (not a wrapped { links: [...] } envelope).

pub async fn get_link_types(&self) -> Result<Vec<JiraLinkType>>

Lists available issue link types.

pub async fn create_issue_link( &self, type_name: &str, inward_key: &str, outward_key: &str, ) -> Result<()>

Creates a link between two JIRA issues.

pub async fn remove_issue_link(&self, link_id: &str) -> Result<()>

Removes an issue link by ID.

pub async fn set_issue_parent( &self, issue_key: &str, parent_key: &str, ) -> Result<()>

Sets the parent of a JIRA issue (e.g., links a Story to its Epic, a Sub-task to its Story, or any issue to a parent of a hierarchy-allowed type).

pub async fn get_issue_id(&self, key: &str) -> Result<String>

Resolves a JIRA issue key to its numeric ID.

pub async fn get_dev_status_summary( &self, key: &str, ) -> Result<JiraDevStatusSummary>

Fetches a development status summary (counts per category) for a JIRA issue.

Uses the DevStatus summary endpoint. Returns counts and provider names for each category (pull requests, branches, repositories).

pub async fn get_dev_status( &self, key: &str, data_type: Option<&str>, application_type: Option<&str>, ) -> Result<JiraDevStatus>

Fetches development status (PRs, branches, repositories) for a JIRA issue.

Uses the DevStatus API which requires the numeric issue ID. The key is resolved automatically via get_issue_id.

If application_type is None, discovers available providers via the summary endpoint and queries each one. If Some, queries only that provider (e.g., “GitHub”, “bitbucket”, “stash”).

pub async fn get_attachments(&self, key: &str) -> Result<Vec<JiraAttachment>>

Gets attachment metadata for a JIRA issue.

pub async fn get_changelog( &self, key: &str, limit: u32, ) -> Result<Vec<JiraChangelogEntry>>

Gets the changelog for a JIRA issue with auto-pagination.

pub async fn get_fields(&self) -> Result<Vec<JiraField>>

Lists all JIRA field definitions.

pub async fn get_field_contexts(&self, field_id: &str) -> Result<Vec<String>>

Lists options for a JIRA custom field. Lists contexts for a JIRA custom field.

pub async fn get_field_options( &self, field_id: &str, context_id: Option<&str>, ) -> Result<Vec<JiraFieldOption>>

Lists options for a JIRA custom field.

When context_id is None, auto-discovers the first context for the field.

pub async fn get_projects(&self, limit: u32) -> Result<JiraProjectList>

Lists JIRA projects.

pub async fn delete_issue(&self, key: &str) -> Result<()>

Deletes a JIRA issue.

pub async fn get_watchers(&self, key: &str) -> Result<JiraWatcherList>

Lists watchers on a JIRA issue.

pub async fn add_watcher(&self, key: &str, account_id: &str) -> Result<()>

Adds a user as a watcher on a JIRA issue.

pub async fn remove_watcher(&self, key: &str, account_id: &str) -> Result<()>

Removes a user from watchers on a JIRA issue.

pub async fn get_myself(&self) -> Result<JiraUser>

Verifies authentication by fetching the current user.