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>, custom_fields: &BTreeMap<String, Value>, ) -> Result<()>

Updates a JIRA issue with any subset of supported fields.

description_adf and summary 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_10088). The system parent field is set via Self::set_issue_parent, not here. 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_10088).

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_project_create_meta( &self, project_key: &str, issue_type: &str, ) -> Result<CreateMeta>

Introspects the create screen for a project + issue type, returning each field with its required flag, schema type, allowed values, and default.

GET /rest/api/3/issue/createmeta?projectKeys={p}&issuetypeNames={t}&expand=projects.issuetypes.fields — the same endpoint as get_createmeta, parsed for the full field metadata an agent needs to prompt before creating.

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 delete_comment(&self, key: &str, comment_id: &str) -> Result<()>

Deletes a comment from a JIRA issue.

Issues a DELETE /rest/api/3/issue/{key}/comment/{id} (204 on success).

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 update_worklog( &self, key: &str, worklog_id: &str, time_spent: Option<&str>, started: Option<&str>, comment: Option<&str>, ) -> Result<()>

Updates an existing worklog entry on a JIRA issue.

Issues a PUT /rest/api/3/issue/{key}/worklog/{id} with only the fields that are Some; omitted fields keep their current value. The comment is sent as an ADF document, mirroring Self::add_worklog.

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

Deletes a worklog entry from a JIRA issue.

Issues a DELETE /rest/api/3/issue/{key}/worklog/{id} (204 on success).

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

Lists available transitions for a JIRA issue.

pub async fn get_transitions_with_fields( &self, key: &str, ) -> Result<(Vec<JiraTransition>, BTreeMap<String, EditMeta>)>

Lists available transitions for a JIRA issue together with each transition’s screen-field metadata.

Requests expand=transitions.fields so screen fields can be resolved for execute --set-field/--resolution and so a mandatory-comment screen can be detected. Returns the same JiraTransition list as Self::get_transitions plus a map keyed by transition id holding the screen EditMeta; screenless transitions have no entry.

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

Executes a transition on a JIRA issue.

Thin shim over Self::do_transition_with_fields that sends no screen fields and no transition comment.

pub async fn do_transition_with_fields( &self, key: &str, transition_id: &str, fields: &BTreeMap<String, Value>, comment: Option<&ValidatedAdfDocument>, ) -> Result<()>

Executes a transition, optionally setting transition-screen fields and adding a comment in the same request.

fields is a map of stable JIRA field id → API-shaped value (e.g. resolution → {"name": "Fixed"}); it is omitted from the body when empty. When comment is Some, it is added via the transition update.comment operation so it lands atomically with the transition — the only way to satisfy a transition screen that mandates a comment.

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_jira_user(&self, account_id: &str) -> Result<JiraUserRecord>

Resolves a single JIRA user by account ID (GET /rest/api/3/user?accountId=).

Failure-tolerant: an unknown / anonymised account (HTTP 404) or any other non-auth failure resolves to a stub record with error set rather than an Err, so a batch lookup never aborts for one bad ID. A 401 (bad credentials) is a hard error worth surfacing. Deactivated accounts come back from Atlassian as a real 200 record with active: false.

pub async fn get_jira_users( &self, account_ids: &[String], ) -> Result<JiraUserGetResults>

Resolves multiple JIRA users by account ID, concurrently.

Each ID is fetched independently via Self::get_jira_user; per-ID failures become stub records, so the batch only errors on a genuine auth failure (or transport error). Results preserve request order.

pub async fn get_confluence_user( &self, account_id: &str, ) -> Result<ConfluenceUserRecord>

Resolves a single Confluence user by account ID (GET /wiki/rest/api/user?accountId=).

Failure-tolerant in the same way as Self::get_jira_user. The v1 user object has no active flag, so ConfluenceUserRecord::active is always None; displayName falls back to publicName.

pub async fn get_confluence_users( &self, account_ids: &[String], ) -> Result<ConfluenceUserGetResults>

Resolves multiple Confluence users by account ID, concurrently.

Behaves like Self::get_jira_users: per-ID failures become stub records; the batch only errors on a genuine auth / transport failure.

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 delete_sprint(&self, sprint_id: u64) -> Result<()>

Deletes a sprint.

Issues DELETE /rest/agile/1.0/sprint/{id}.

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 update_project_version( &self, version_id: &str, name: Option<&str>, description: Option<&str>, released: Option<bool>, release_date: Option<&str>, archived: Option<bool>, start_date: Option<&str>, ) -> Result<()>

Updates an existing project version — the shared backend for release / archive / rename / edit.

Issues PUT /rest/api/3/version/{id} with only the Some fields; omitted fields keep their current value. Any provided dates are validated first. Returns () (mirroring Self::update_sprint); the caller already knows the mutation it requested.

pub async fn delete_project_version( &self, version_id: &str, move_fix_issues_to: Option<&str>, move_affected_issues_to: Option<&str>, ) -> Result<()>

Deletes a project version.

Issues DELETE /rest/api/3/version/{id}. Issues that reference the version can be reassigned first via moveFixIssuesTo / moveAffectedIssuesTo (each a target version id); omit both to delete and simply drop the references.

pub async fn get_project_components( &self, project_key: &str, ) -> Result<Vec<JiraComponent>>

Lists the components of a JIRA project.

GET /rest/api/3/project/{key}/components.

pub async fn create_component( &self, project_key: &str, name: &str, description: Option<&str>, ) -> Result<JiraComponent>

Creates a component on a JIRA project.

POST /rest/api/3/component.

pub async fn update_component( &self, component_id: &str, name: Option<&str>, description: Option<&str>, ) -> Result<()>

Updates a JIRA component’s name and/or description.

PUT /rest/api/3/component/{id} with only the Some fields.

pub async fn delete_component( &self, component_id: &str, move_issues_to: Option<&str>, ) -> Result<()>

Deletes a JIRA component.

DELETE /rest/api/3/component/{id}. Issues that reference the component can be reassigned via moveIssuesTo (another component id).

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 create_remote_issue_link( &self, key: &str, url: &str, title: &str, summary: Option<&str>, relationship: Option<&str>, global_id: Option<&str>, ) -> Result<String>

Creates (or, when global_id matches an existing link, updates) a remote (external-URL) link on a JIRA issue.

Issues POST /rest/api/3/issue/{key}/remotelink. Returns the new/updated link’s id (normalized to String, since JIRA returns it as a number).

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

Deletes a remote (external-URL) link from a JIRA issue by its link id.

Issues DELETE /rest/api/3/issue/{key}/remotelink/{linkId}.

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 modify_issue_labels( &self, key: &str, add: &[String], remove: &[String], ) -> Result<()>

Incrementally adds and/or removes labels on a JIRA issue.

Issues PUT /rest/api/3/issue/{key} with the update verb ({"update": {"labels": [{"add": …}, {"remove": …}]}}), so labels not mentioned are preserved — unlike a full-array fields.labels replace (which jira write --set labels=… performs).

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 providers (each carrying both the applicationType instance-type key and its display name) 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 upload_attachments( &self, key: &str, files: &[PathBuf], ) -> Result<Vec<JiraAttachment>>

Uploads one or more files as attachments to a JIRA issue.

Streams each file body — files are never fully buffered in memory. All files ride a single multipart POST (JIRA accepts repeated file parts), and the endpoint returns metadata for every created attachment.

Sends X-Atlassian-Token: no-check (Atlassian’s XSRF opt-out required on this endpoint). Does not retry on 429: see AtlassianClient::post_multipart.

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

Deletes a JIRA attachment by ID.

DELETE /rest/api/3/attachment/{id} — permanent (JIRA has no trash).

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.