Documentation
¶
Overview ¶
Package jira implements an HTTP client for the Jira Cloud REST API v3.
Index ¶
- Constants
- func ADFToMarkdown(body any) string
- func ADFToPlainText(body any) string
- func MarkdownToADF(source string) (map[string]any, error)
- func RolePriority(roleName string) int
- func ValidateBaseURL(rawURL string) error
- type APIError
- type ChangeItem
- type ChangelogEntry
- type Comment
- type CommentPage
- type EntityPropertyValue
- type Issue
- type IssueFields
- type LiveClient
- func (c *LiveClient) CreateComment(ctx context.Context, issueIDOrKey, body string) (*Comment, error)
- func (c *LiveClient) DeleteEntityProperty(ctx context.Context, issueIDOrKey, propertyKey string) error
- func (c *LiveClient) GetEntityProperty(ctx context.Context, issueIDOrKey, propertyKey string) (json.RawMessage, error)
- func (c *LiveClient) GetIssue(ctx context.Context, issueIDOrKey string) (*Issue, error)
- func (c *LiveClient) GetMyself(ctx context.Context) (*User, error)
- func (c *LiveClient) GetProjectRoleActors(ctx context.Context, projectKey string) (map[string]ProjectRoleActors, error)
- func (c *LiveClient) GetStatus(ctx context.Context, idOrName string) (*Status, error)
- func (c *LiveClient) GetUserGroups(ctx context.Context, accountID string) ([]UserGroupInfo, error)
- func (c *LiveClient) ListChangelog(ctx context.Context, issueIDOrKey string) ([]ChangelogEntry, error)
- func (c *LiveClient) ListComments(ctx context.Context, issueIDOrKey string) ([]Comment, error)
- func (c *LiveClient) SearchIssues(ctx context.Context, jql string, limit int) ([]Issue, error)
- func (c *LiveClient) SetEntityProperty(ctx context.Context, issueIDOrKey, propertyKey string, value any) error
- func (c *LiveClient) UpdateComment(ctx context.Context, issueIDOrKey, commentID, body string) error
- type Option
- type ProjectRoleActors
- type ProjectRoleDetail
- type ProjectRoleList
- type RoleActor
- type RoleActorGroup
- type RoleActorUser
- type SearchResult
- type Status
- type StatusCategory
- type User
- type UserGroupInfo
Constants ¶
const MaxMarkdownBytes = maxMarkdownParseBytes
MaxMarkdownBytes is the exported form of maxMarkdownParseBytes, for callers that assemble a markdown body destined for CreateComment/ UpdateComment (or MarkdownToADF directly) and need to cap its size before hitting the limit at write time rather than after.
Variables ¶
This section is empty.
Functions ¶
func ADFToMarkdown ¶ added in v0.37.0
ADFToMarkdown converts a Jira issue or comment body to CommonMark Markdown, the reverse of MarkdownToADF. body is either a plain string or an ADF document (map[string]any), matching the two shapes Jira's REST API returns for description/body fields; any other type (including nil) yields "".
Unlike ADFToPlainText, this preserves formatting (bold/italic/code/ links, headings, lists, blockquotes, code blocks) rather than discarding it: tracker.Body is documented as Markdown-formatted text, so a Jira-backed tracker.Client returning plain text there would silently drop content GitHub- and GitLab-backed implementations preserve.
func ADFToPlainText ¶ added in v0.37.0
ADFToPlainText extracts plain text from a Jira issue or comment body. body is either a plain string or an ADF document (map[string]any), matching the two shapes Jira's REST API returns for description/body fields; any other type (including nil) yields "".
func MarkdownToADF ¶ added in v0.37.0
MarkdownToADF parses source as CommonMark and returns an Atlassian Document Format (ADF) "doc" node, since Jira's comment/description fields don't accept markdown directly. It supports the block/inline vocabulary ADFToPlainText (and the read-side walker it mirrors in internal/jirapoll) already recognizes: paragraphs, headings, bullet/ordered lists, blockquotes, fenced/indented code blocks, thematic breaks, and the strong/em/code/link/hardBreak inline marks. Block-level constructs outside that vocabulary (raw HTML, tables, ...) fall back to a plain-text paragraph of their raw source rather than vanishing outright — ADF has no equivalent node for most of them, but dropping the content entirely would silently lose whatever a caller wrote (e.g. this repo's own <details> convention for collapsing output).
Returns an error, rather than a partial or empty result, if source is over maxMarkdownParseBytes or if it converts to no ADF content at all (e.g. markdown that's nothing but a chain of nested blockquotes deeper than maxADFWriteDepth): callers write the result straight to Jira, and silently posting a truncated or visibly empty comment is worse than failing the write.
func RolePriority ¶ added in v0.36.0
RolePriority returns the priority of a Jira project role name. Higher values take precedence when a user appears in multiple roles.
KNOWN LIMITATION (intentional for the MVP): matches by role name, not by the project's permission scheme. See mapJiraRole in internal/jirapoll and docs/guides/user/jira-integration.md#actor-role-resolution.
func ValidateBaseURL ¶ added in v0.37.0
ValidateBaseURL checks that the base URL uses https, unless it points to a loopback address (for httptest servers), and rejects embedded credentials. Exported so other Jira-backed clients (e.g. tracker.JiraClient) can apply the same policy to base URLs they accept.
Types ¶
type APIError ¶
APIError represents an error response from the Jira API.
func (*APIError) IsTransient ¶ added in v0.37.0
IsTransient reports whether the API error represents a transient failure that may succeed on retry: server errors (500–504) and rate limits (429). This method satisfies the transientReporter interface used by forge.IsTransient.
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) CreateComment ¶ added in v0.37.0
func (c *LiveClient) CreateComment(ctx context.Context, issueIDOrKey, body string) (*Comment, error)
CreateComment adds a new comment to an issue. body is markdown; it's converted to ADF before being sent, since Jira Cloud doesn't accept markdown directly.
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) GetMyself ¶
func (c *LiveClient) GetMyself(ctx context.Context) (*User, error)
GetMyself returns the currently authenticated user.
func (*LiveClient) GetProjectRoleActors ¶ added in v0.36.0
func (c *LiveClient) GetProjectRoleActors(ctx context.Context, projectKey string) (map[string]ProjectRoleActors, error)
GetProjectRoleActors returns the direct users and group assignments for each project role without enumerating group members. This avoids the 100-page pagination cap on the group/member endpoint that used to truncate large groups. Callers combine the returned structure with GetUserGroups for per-actor resolution.
func (*LiveClient) GetStatus ¶
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) GetUserGroups ¶ added in v0.36.0
func (c *LiveClient) GetUserGroups(ctx context.Context, accountID string) ([]UserGroupInfo, error)
GetUserGroups returns the groups that the specified user belongs to, for per-actor role resolution that is not subject to the group/member pagination cap (see GetProjectRoleActors).
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 ¶
ListComments fetches all comments on an issue, exhausting pagination up to maxListPages pages.
func (*LiveClient) SearchIssues ¶
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.
func (*LiveClient) UpdateComment ¶ added in v0.37.0
func (c *LiveClient) UpdateComment(ctx context.Context, issueIDOrKey, commentID, body string) error
UpdateComment replaces the body of an existing comment. body is markdown; it's converted to ADF before being sent, for the same reason as CreateComment.
type Option ¶
type Option func(*LiveClient)
Option configures the Jira client.
func WithBaseURL ¶
WithBaseURL sets a custom base URL for the Jira instance.
func WithEmail ¶
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 ¶
WithHTTPClient sets a custom HTTP client for API calls.
type ProjectRoleActors ¶ added in v0.36.0
type ProjectRoleActors struct {
DirectUsers map[string]bool // accountIDs directly assigned to this role
GroupIDs []string // group IDs assigned to this role
}
ProjectRoleActors describes the direct users and group assignments for a project role without enumerating group members, so it is not subject to the group/member pagination cap.
type ProjectRoleDetail ¶
ProjectRoleDetail is the response from GET /rest/api/3/project/{key}/role/{id}.
type ProjectRoleList ¶
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 ¶
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.
type UserGroupInfo ¶ added in v0.36.0
type UserGroupInfo struct {
Name string `json:"name"`
GroupID string `json:"groupId"`
Self string `json:"self"`
}
UserGroupInfo represents a group returned by GET /rest/api/3/user/groups. Used for per-actor role resolution that checks the actor's group memberships instead of enumerating all members of a role-assigned group.