Struct Client 

pub struct Client { /* private fields */ }

A configured Tracker client.

Implementations

impl Client

pub fn new(config: &ClientConfig) -> Result<Self, ApiError>

pub async fn myself(&self) -> Result<User, ApiError>

GET /v3/myself — the cheapest call that proves the whole chain works: token, organisation header, and network.

pub async fn issue(&self, key: &str) -> Result<(Issue, Value), ApiError>

One issue, both normalised and raw.

The raw payload travels alongside so that --json-raw does not cost a second request, and so that a field we do not model is still reachable.

pub async fn issue_links(&self, key: &str) -> Result<Vec<Link>, ApiError>

The links of an issue, with their direction resolved.

Tracker keeps links on their own endpoint, so the compact issue view costs two requests. Showing links is worth that: “what blocks this” is the question that follows “what is this”, and making the caller ask twice costs more than one round trip (ADR 3).

pub async fn issue_remote_links( &self, key: &str, ) -> Result<Vec<RemoteLink>, ApiError>

GET /v3/issues/{key}/remotelinks — the links that leave Tracker.

Its own request rather than a second section of Self::issue_links: most issues have none, and making every issue links pay for a request that usually answers [] is the wrong trade.

pub async fn search( &self, query: &str, page: u32, per_page: u32, ) -> Result<Page<Issue>, ApiError>

One page of search results.

Tracker reports the total in X-Total-Count. When it does not, the page still has to be honest about whether more exists, which is why Page::has_more falls back to “a full page probably is not the last”.

pub async fn count(&self, query: &str) -> Result<u64, ApiError>

How many issues match, without fetching any of them.

pub async fn create_issue(&self, body: &Value) -> Result<Issue, ApiError>

POST /v3/issues/ — create an issue, returning it normalised.

pub async fn update_issue( &self, key: &str, body: &Value, ) -> Result<Issue, ApiError>

PATCH /v3/issues/{key} — change fields.

pub async fn add_comment( &self, key: &str, text: &str, ) -> Result<Comment, ApiError>

POST /v3/issues/{key}/comments — add a comment.

pub async fn update_comment( &self, key: &str, id: &str, text: &str, ) -> Result<Comment, ApiError>

Rewrite a comment that is already there.

Tracker keeps no history of the previous text and shows the comment as edited, so this replaces rather than appends: the old wording is gone.

pub async fn delete_comment(&self, key: &str, id: &str) -> Result<(), ApiError>

Remove a comment.

pub async fn update_worklog( &self, key: &str, id: &str, body: &Value, ) -> Result<Worklog, ApiError>

Correct a worklog entry that is already recorded.

pub async fn worklogs(&self, key: &str) -> Result<Vec<Worklog>, ApiError>

GET /v3/issues/{key}/worklog — every entry, oldest first.

pub async fn add_worklog( &self, key: &str, body: &Value, ) -> Result<Worklog, ApiError>

POST /v3/issues/{key}/worklog — record time spent.

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

DELETE /v3/issues/{key}/worklog/{id}.

pub async fn checklist(&self, key: &str) -> Result<Vec<ChecklistItem>, ApiError>

GET /v3/issues/{key}/checklistItems.

pub async fn add_checklist_item( &self, key: &str, body: &Value, ) -> Result<Vec<ChecklistItem>, ApiError>

POST /v3/issues/{key}/checklistItems — add a line.

Tracker answers with the whole issue rather than the item, so the list comes back out of the issue’s own checklistItems.

pub async fn update_checklist_item( &self, key: &str, id: &str, body: &Value, ) -> Result<Vec<ChecklistItem>, ApiError>

PATCH /v3/issues/{key}/checklistItems/{id} — tick, untick or reword.

pub async fn delete_checklist_item( &self, key: &str, id: &str, ) -> Result<(), ApiError>

DELETE /v3/issues/{key}/checklistItems/{id}.

pub async fn add_link( &self, key: &str, relationship: &str, other: &str, ) -> Result<(), ApiError>

POST /v3/issues/{key}/links — link two issues.

pub async fn delete_link(&self, key: &str, id: &str) -> Result<(), ApiError>

DELETE /v3/issues/{key}/links/{id}.

pub async fn transitions(&self, key: &str) -> Result<Vec<Transition>, ApiError>

Transitions available from the issue’s current status.

pub async fn execute_transition( &self, key: &str, transition: &str, body: &Value, ) -> Result<(), ApiError>

Perform a transition.

pub async fn entities( &self, kind: &str, input: Option<&str>, page: u32, per_page: u32, ) -> Result<Page<Entity>, ApiError>

Search projects, portfolios or goals.

The entity endpoints answer with their own envelope (values, hits, pages) rather than the header-based totals the issue endpoints use, so the page is assembled from the body here.

pub async fn entities_in( &self, parent: &str, page: u32, per_page: u32, ) -> Result<Page<Entity>, ApiError>

What a portfolio contains: the portfolios and projects under it.

Two requests, because the entity endpoints are typed and containment is not: a portfolio holds both. The tally sums the two totals, so shown N of M is the real count even though a page is a page of each.

pub async fn entity(&self, kind: &str, id: &str) -> Result<Entity, ApiError>

One project, portfolio or goal, by the id the entity endpoints use.

pub async fn attachments(&self, key: &str) -> Result<Vec<Attachment>, ApiError>

The attachments of an issue.

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

Download an attachment’s bytes.

The download URL comes out of the payload, which means it is supplied by the server rather than chosen by us. It is checked against the configured API host before being followed: a crafted content URL must not be able to send this client, carrying its OAuth header, to somewhere else.

pub async fn upload( &self, key: &str, filename: &str, bytes: Vec<u8>, ) -> Result<Attachment, ApiError>

Upload a file to an issue.

pub async fn queues(&self) -> Result<Vec<Queue>, ApiError>

Queues visible to the active profile.

Tracker paginates this endpoint; the ceiling is deliberately generous because “how many queues can I see” is a question with a small answer, and a second page here would be surprising.

pub async fn worklog_search( &self, who: Option<&str>, since: Option<&str>, until: Option<&str>, per_page: u32, ) -> Result<Vec<Worklog>, ApiError>

Worklog entries across the whole organisation.

createdBy takes a login or a uid and not me: Tracker reads it as a login and answers 422 saying no such user exists. Resolving me is the caller’s job, with one extra request to myself.

pub async fn move_issue( &self, key: &str, queue: &str, keep_fields: bool, initial_status: bool, ) -> Result<Issue, ApiError>

Move an issue to another queue.

The issue keeps its identity and loses its name: PROJ-42 becomes OTHER-17, and there is no request that undoes it. Tracker drops fields the target queue does not define unless moveAllFields says otherwise, so that choice is the caller’s rather than a default we picked for them.

pub async fn changelog( &self, key: &str, per_page: u32, ) -> Result<Vec<Change>, ApiError>

What changed on an issue, newest last.

Tracker pages this with an opaque cursor rather than page numbers, and the cursor is only worth spending when somebody asks for more than the first page — which nobody has yet. So this asks for one page, and the caller says how big.

pub async fn queue_versions(&self, key: &str) -> Result<Vec<Version>, ApiError>

The versions a queue defines.

This is what an issue’s fixVersions refers to; without it that field is an id with no meaning.

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

The tags in use in a queue.

pub async fn queue_automation(&self, key: &str) -> Result<Automation, ApiError>

Everything that changes issues in a queue on its own.

Three requests, and a refusal of one of them is an answer rather than a failure: triggers need queue-owner rights, so a member of the queue gets two sections and Tracker’s own words about the third. All three failing is a different thing — a queue that is not there, or a token that is not allowed — and is reported as the error it is.

pub async fn dictionary( &self, kind: Dictionary, ) -> Result<Vec<DictEntry>, ApiError>

One of the four organisation-wide dictionaries.

Small and unpaged — the largest of the four is statuses, in the dozens — so this asks for the whole thing and says nothing about pages.

pub async fn users( &self, page: u32, per_page: u32, ) -> Result<Page<Person>, ApiError>

One page of the organisation’s directory.

Paged, unlike the dictionaries: an organisation has as many people in it as it has people, and the one this was written against already answers with a three-figure total.

pub async fn user(&self, who: &str) -> Result<Person, ApiError>

One person, by login or by uid.

There is no users/me: Tracker answers 404 for it, and myself is the endpoint that question belongs to.

pub async fn boards(&self) -> Result<Vec<Board>, ApiError>

Boards visible to the active profile.

Not paginated by the endpoint, and not by us: an organisation has boards in the dozens, not the thousands.

pub async fn board(&self, id: &str) -> Result<Board, ApiError>

One board.

pub async fn sprints(&self, board: &str) -> Result<Vec<Sprint>, ApiError>

The sprints of a board.

A board that cannot have sprints answers with a refusal rather than an empty list, and that refusal is passed through as Tracker worded it: a kanban board having no sprints is Tracker’s answer to the question, not a failure of the command, and inventing an empty list here would hide which of the two happened.

pub async fn all_sprints(&self) -> Result<Vec<Sprint>, ApiError>

Every sprint in the organisation.

board sprints ID needs the board first, and a sprint name is a thing people say without knowing which board it belongs to. This is the same records with the board named on each.

pub async fn queue_local_fields( &self, key: &str, ) -> Result<Vec<FieldSpec>, ApiError>

The fields a queue defines itself.

Not a subset of Self::queue_fields, which lists everything the queue can use: a local field belongs to the queue, is invisible to the organisation-wide listing, and cannot be fetched through /v3/fields at all. So these carry their full definition — what they accept included — because there is no second command that could answer that for them.

pub async fn create_entity( &self, kind: &str, fields: &Value, ) -> Result<Entity, ApiError>

Create a project, portfolio or goal with nothing but a name.

Everything else about an entity is optional, and a command line is not where a portfolio’s description gets written.

pub async fn delete_entity(&self, kind: &str, id: &str) -> Result<(), ApiError>

Delete a project, portfolio or goal.

Entities can be deleted; issues cannot. That asymmetry is why the live suite may write entities and may not write issues without being told a queue to sacrifice.

pub async fn update_entity( &self, kind: &str, id: &str, fields: &Value, version: Option<u64>, ) -> Result<Entity, ApiError>

Change the fields of a project, portfolio or goal.

Quotes the version for the same reason Self::place_entity does: a write without one lands on top of whatever happened in between.

pub async fn place_entity( &self, kind: &str, id: &str, parent: Option<&str>, version: Option<u64>, ) -> Result<Entity, ApiError>

Put an entity inside a portfolio, or take it out of one.

version is Tracker’s optimistic-concurrency counter and is quoted on purpose: without it the write lands whatever happened in between, and with it a portfolio that moved under us answers 412 instead of being silently overwritten.

pub async fn queue(&self, key: &str) -> Result<QueueSettings, ApiError>

One queue and its settings.

pub async fn queue_blueprint(&self, key: &str) -> Result<Blueprint, ApiError>

The parts of a queue that another queue can be built from.

issueTypesConfig pairs each issue type with a workflow and a set of resolutions, and workflow ids are organisation-specific strings nobody has memorised. Copying them from a queue that already works is the only way to create one from a command line without asking for internals.

pub async fn create_queue( &self, body: &Value, ) -> Result<QueueSettings, ApiError>

Create a queue.

pub async fn fields(&self) -> Result<Vec<QueueField>, ApiError>

Every field defined in the organisation, not just one queue’s.

queue fields answers “what can I set on an issue here”; this answers “what exists at all”, which is the question behind a field that a queue does not show.

pub async fn field(&self, key: &str) -> Result<FieldSpec, ApiError>

One field’s definition, by the key queue fields prints.

A local field defined inside one queue is not reachable here — it lives under the queue — and Tracker answers 404 for it, which is the honest answer rather than one worth papering over.

pub async fn templates( &self, kind: TemplateKind, ) -> Result<Vec<Template>, ApiError>

Issue or comment templates.

The path is issueTemplates and commentTemplates; there is no _templates collection, which is worth writing down because every plausible guess at one answers 400 or 404.

pub async fn issue_comments(&self, key: &str) -> Result<Vec<Comment>, ApiError>

The comments of an issue.

Fetched in one generous page: an issue with more than a hundred comments is rare enough that paginating here would cost more in complexity than it saves anyone.

pub async fn queue_fields(&self, key: &str) -> Result<Vec<QueueField>, ApiError>

The fields of a queue, including custom ones, as (key, name, type).

Trait Implementations

impl Clone for Client

fn clone(&self) -> Client

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Client

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.