jira

package
v0.35.1 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Aug 7, 2026 License: Apache-2.0 Imports: 18 Imported by: 0

Documentation

Overview

Package jira implements an HTTP client for the Jira Cloud REST API v3.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type APIError

type APIError struct {
	StatusCode int
	Message    string
}

APIError represents an error response from the Jira API.

func (*APIError) Error

func (e *APIError) Error() string

func (*APIError) Unwrap

func (e *APIError) Unwrap() error

type ChangeItem

type ChangeItem struct {
	Field      string `json:"field"`
	From       string `json:"from"` // Stable ID of the previous value (e.g. status ID); survives renames
	To         string `json:"to"`   // Stable ID of the new value
	FromString string `json:"fromString"`
	ToString   string `json:"toString"`
}

ChangeItem describes a single field change within a changelog entry.

type ChangelogEntry

type ChangelogEntry struct {
	ID      string       `json:"id"`
	Author  User         `json:"author"`
	Created string       `json:"created"`
	Items   []ChangeItem `json:"items"`
}

ChangelogEntry represents a single changelog entry on a Jira issue.

type Comment

type Comment struct {
	ID   string `json:"id"`
	Body any    `json:"body"` // ADF object or string
	// Author is the account that originally created the comment;
	// UpdateAuthor is the account that last modified it (set by Jira on
	// edit). They differ when someone with Edit-All-Comments edits another
	// user's comment — the poller must attribute an edit-detected event to
	// the editor, not the author, to avoid running attacker-authored text
	// under the original author's role.
	Author       User   `json:"author"`
	UpdateAuthor User   `json:"updateAuthor"`
	Created      string `json:"created"`
	Updated      string `json:"updated"`
}

Comment represents a single comment on a Jira issue.

type CommentPage

type CommentPage struct {
	Comments   []Comment `json:"comments"`
	Total      int       `json:"total"`
	MaxResults int       `json:"maxResults"`
	StartAt    int       `json:"startAt"`
}

CommentPage is a paginated list of comments.

type EntityPropertyValue

type EntityPropertyValue struct {
	Key   string          `json:"key"`
	Value json.RawMessage `json:"value"`
}

EntityPropertyValue wraps a JSON value stored as a Jira entity property.

type Issue

type Issue struct {
	ID     string      `json:"id"`
	Key    string      `json:"key"`
	Self   string      `json:"self"`
	Fields IssueFields `json:"fields"`
}

Issue represents a Jira issue.

type IssueFields

type IssueFields struct {
	Summary     string       `json:"summary"`
	Description any          `json:"description"` // ADF object or string
	Status      Status       `json:"status"`
	Labels      []string     `json:"labels"`
	Reporter    User         `json:"reporter"`
	Created     string       `json:"created"`
	Updated     string       `json:"updated"`
	Comment     *CommentPage `json:"comment,omitempty"`
}

IssueFields contains the standard fields of a Jira issue.

type LiveClient

type LiveClient struct {
	// contains filtered or unexported fields
}

LiveClient is an HTTP client for the Jira Cloud REST API v3.

func New

func New(token string, opts ...Option) (*LiveClient, error)

New creates a new Jira client with the given API token.

func (*LiveClient) DeleteEntityProperty

func (c *LiveClient) DeleteEntityProperty(ctx context.Context, issueIDOrKey, propertyKey string) error

DeleteEntityProperty removes an entity property from an issue.

func (*LiveClient) GetEntityProperty

func (c *LiveClient) GetEntityProperty(ctx context.Context, issueIDOrKey, propertyKey string) (json.RawMessage, error)

GetEntityProperty retrieves the value of an entity property on an issue. Returns forge.ErrNotFound (wrapped) if the property does not exist.

func (*LiveClient) GetIssue

func (c *LiveClient) GetIssue(ctx context.Context, issueIDOrKey string) (*Issue, error)

GetIssue fetches a single issue by ID or key.

func (*LiveClient) GetMyself

func (c *LiveClient) GetMyself(ctx context.Context) (*User, error)

GetMyself returns the currently authenticated user.

func (*LiveClient) GetProjectRoleMembership

func (c *LiveClient) GetProjectRoleMembership(ctx context.Context, projectKey string) (map[string]string, error)

GetProjectRoleMembership returns a map of accountID → role name for all members of the given Jira project. Role names are the Jira project role names (e.g. "Administrators", "Developers"). When a user appears in multiple roles, the highest-priority role wins (Administrators > Developers > everything else).

func (*LiveClient) GetStatus

func (c *LiveClient) GetStatus(ctx context.Context, idOrName string) (*Status, error)

GetStatus fetches a single status by ID or name, including its statusCategory. Used to classify changelog status transitions by category rather than by matching locale/workflow-specific status name substrings.

func (*LiveClient) ListChangelog

func (c *LiveClient) ListChangelog(ctx context.Context, issueIDOrKey string) ([]ChangelogEntry, error)

ListChangelog fetches all changelog entries for an issue, exhausting pagination up to maxListPages pages.

func (*LiveClient) ListComments

func (c *LiveClient) ListComments(ctx context.Context, issueIDOrKey string) ([]Comment, error)

ListComments fetches all comments on an issue, exhausting pagination up to maxListPages pages.

func (*LiveClient) SearchIssues

func (c *LiveClient) SearchIssues(ctx context.Context, jql string, limit int) ([]Issue, error)

SearchIssues executes a JQL search and returns up to limit matching issues, using the POST /rest/api/3/search/jql endpoint with cursor-based pagination (nextPageToken + isLast). Pagination stops as soon as limit issues have been collected, so a limit smaller than the full match set bounds API cost rather than fetching everything and truncating afterward. A limit <= 0 fetches all matching issues, capped at maxSearchPages pages (10,000 issues at 50 per page) to prevent unbounded memory growth.

This endpoint is eventually consistent: Atlassian documents that recent updates might not be immediately visible in results. For the poller that only means an issue can appear (or re-sort under ORDER BY updated) a cycle late — per-issue checkpoints come from the strongly-consistent direct comment/changelog GETs, never from search results, so no events are lost. Do not "fix" ordering assumptions by trusting search freshness.

func (*LiveClient) SetEntityProperty

func (c *LiveClient) SetEntityProperty(ctx context.Context, issueIDOrKey, propertyKey string, value any) error

SetEntityProperty sets (creates or updates) an entity property on an issue.

type Option

type Option func(*LiveClient)

Option configures the Jira client.

func WithBaseURL

func WithBaseURL(rawURL string) Option

WithBaseURL sets a custom base URL for the Jira instance.

func WithEmail

func WithEmail(email string) Option

WithEmail sets the email address for Basic auth (Jira Cloud). When set, the client uses Authorization: Basic base64(email:token). When empty, the client uses Authorization: Bearer token (Cloud PAT). Note: despite the Bearer-auth option, this client's REST endpoints are Cloud-only (see apiURL) — Data Center is not currently supported.

func WithHTTPClient

func WithHTTPClient(client *http.Client) Option

WithHTTPClient sets a custom HTTP client for API calls.

type ProjectRoleDetail

type ProjectRoleDetail struct {
	Name   string      `json:"name"`
	Actors []RoleActor `json:"actors"`
}

ProjectRoleDetail is the response from GET /rest/api/3/project/{key}/role/{id}.

type ProjectRoleList

type ProjectRoleList map[string]string

ProjectRoleList is the response from GET /rest/api/3/project/{key}/role. It maps role names to their URLs. Example: {"Administrators": "https://.../role/10002", "Developers": "https://.../role/10001"}

type RoleActor

type RoleActor struct {
	ID          int             `json:"id"`
	DisplayName string          `json:"displayName"`
	Type        string          `json:"type"` // "atlassian-user-role-actor", "atlassian-group-role-actor"
	ActorUser   *RoleActorUser  `json:"actorUser,omitempty"`
	ActorGroup  *RoleActorGroup `json:"actorGroup,omitempty"`
}

RoleActor represents a member of a project role.

type RoleActorGroup

type RoleActorGroup struct {
	GroupID string `json:"groupId"`
	Name    string `json:"name"`
}

RoleActorGroup identifies a group granted a project role directly (as opposed to an individual user).

type RoleActorUser

type RoleActorUser struct {
	AccountID string `json:"accountId"`
}

RoleActorUser contains the account ID of a role actor.

type SearchResult

type SearchResult struct {
	Issues        []Issue `json:"issues"`
	NextPageToken string  `json:"nextPageToken,omitempty"`
	IsLast        bool    `json:"isLast"`
}

SearchResult is the response from the POST /rest/api/3/search/jql endpoint. Uses cursor-based pagination (nextPageToken + isLast).

type Status

type Status struct {
	Name           string         `json:"name"`
	StatusCategory StatusCategory `json:"statusCategory"`
}

Status represents the status of a Jira issue.

type StatusCategory

type StatusCategory struct {
	Key string `json:"key"`
}

StatusCategory groups statuses into broad categories. Key is one of "new", "indeterminate", or "done".

type User

type User struct {
	AccountID   string `json:"accountId"`
	Name        string `json:"name"` // Data Center/Server username; unset on Cloud. Unused today since this client only targets Cloud (see apiURL); kept for future Data Center support.
	DisplayName string `json:"displayName"`
	AccountType string `json:"accountType"` // "atlassian", "app", "customer"
	Active      bool   `json:"active"`
}

User represents a Jira user account.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL