linearapi

package
v0.10.0 Latest Latest
Warning

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

 Go to latest Published: Jul 27, 2026 License: MIT Imports: 12 Imported by: 0

Documentation

Index

Constants

View Source 
const (
	// DefaultEndpoint is the default Linear API GraphQL endpoint.
	DefaultEndpoint = "https://api.linear.app/graphql"
)

Variables

This section is empty.

Functions

This section is empty.

Types

type Attachment added in v0.8.0 

type Attachment struct {
	ID         string
	Title      string
	Subtitle   string
	URL        string
	SourceType string
	CreatedAt  time.Time
	UpdatedAt  time.Time
}

Attachment represents an external resource linked to a Linear issue.

type Client 

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

Client is a client for interacting with the Linear GraphQL API.

func NewClient 

func NewClient(cfg ClientConfig) *Client

NewClient creates a new Linear API client with the provided configuration.

func NewClientWithToken 

func NewClientWithToken(token string) *Client

NewClientWithToken creates a new Linear API client with just a token (convenience method).

func (*Client) ArchiveIssue 

func (c *Client) ArchiveIssue(ctx context.Context, issueID string) error

ArchiveIssue archives an issue.

func (*Client) CreateComment 

func (c *Client) CreateComment(ctx context.Context, input CreateCommentInput) (Comment, error)

CreateComment creates a new comment on an issue.

func (*Client) CreateIssue 

func (c *Client) CreateIssue(ctx context.Context, input CreateIssueInput) (Issue, error)

CreateIssue creates a new issue.

func (*Client) CreateIssueRelation added in v0.8.0 

func (c *Client) CreateIssueRelation(ctx context.Context, input CreateIssueRelationInput) (IssueRelation, error)

CreateIssueRelation creates a relation between two issues.

func (*Client) DeleteIssueRelation added in v0.8.0 

func (c *Client) DeleteIssueRelation(ctx context.Context, relationID string) error

DeleteIssueRelation deletes an issue relation.

func (*Client) Endpoint 

func (c *Client) Endpoint() string

Endpoint returns the GraphQL endpoint being used.

func (*Client) FetchIssueByID 

func (c *Client) FetchIssueByID(ctx context.Context, id string) (Issue, error)

FetchIssueByID fetches a single issue by its ID.

func (*Client) FetchIssues 

func (c *Client) FetchIssues(ctx context.Context, params FetchIssuesParams) ([]Issue, error)

FetchIssues fetches issues with optional filtering and sorting. When a search term is provided, it uses Linear's searchIssues query which supports searching by identifier, title, description, and comments.

func (*Client) FetchIssuesPage added in v0.6.0 

func (c *Client) FetchIssuesPage(ctx context.Context, params FetchIssuesParams, after *string) (IssuePage, error)

FetchIssuesPage fetches a single page of issues with optional filtering and sorting. It returns pagination metadata to allow callers to continue fetching.

func (*Client) GetCurrentUser 

func (c *Client) GetCurrentUser(ctx context.Context) (User, error)

GetCurrentUser fetches the current authenticated user.

func (*Client) ListCycles added in v0.8.0 

func (c *Client) ListCycles(ctx context.Context, teamID string) ([]Cycle, error)

ListCycles fetches all non-archived cycles for a team.

func (*Client) ListIssueLabels 

func (c *Client) ListIssueLabels(ctx context.Context, teamID string) ([]IssueLabel, error)

ListIssueLabels fetches both workspace and team labels, merges them, and returns a sorted list. Labels are de-duplicated by ID, with team labels taking precedence.

func (*Client) ListProjectMilestones added in v0.8.0 

func (c *Client) ListProjectMilestones(ctx context.Context, projectID string) ([]ProjectMilestone, error)

ListProjectMilestones fetches all non-archived milestones for a project.

func (*Client) ListProjects 

func (c *Client) ListProjects(ctx context.Context, teamID string) ([]Project, error)

ListProjects fetches all projects for a team.

func (*Client) ListTeamLabels 

func (c *Client) ListTeamLabels(ctx context.Context, teamID string) ([]IssueLabel, error)

ListTeamLabels fetches labels scoped to a specific team.

func (*Client) ListTeams 

func (c *Client) ListTeams(ctx context.Context) ([]Team, error)

ListTeams fetches all teams the user has access to.

func (*Client) ListUsers 

func (c *Client) ListUsers(ctx context.Context, teamID string) ([]User, error)

ListUsers fetches all users in a team.

func (*Client) ListWorkflowStates 

func (c *Client) ListWorkflowStates(ctx context.Context, teamID string) ([]WorkflowState, error)

ListWorkflowStates fetches all workflow states for a team.

func (*Client) ListWorkspaceLabels 

func (c *Client) ListWorkspaceLabels(ctx context.Context) ([]IssueLabel, error)

ListWorkspaceLabels fetches all workspace-level labels (not scoped to a team).

func (*Client) SubscribeToIssue added in v0.8.0 

func (c *Client) SubscribeToIssue(ctx context.Context, issueID string) (Issue, error)

SubscribeToIssue subscribes the current user to an issue.

func (*Client) UnarchiveIssue 

func (c *Client) UnarchiveIssue(ctx context.Context, issueID string) error

UnarchiveIssue unarchives an issue.

func (*Client) UnsubscribeFromIssue added in v0.8.0 

func (c *Client) UnsubscribeFromIssue(ctx context.Context, issueID string) (Issue, error)

UnsubscribeFromIssue unsubscribes the current user from an issue.

func (*Client) UpdateIssue 

func (c *Client) UpdateIssue(ctx context.Context, input UpdateIssueInput) (Issue, error)

UpdateIssue updates an existing issue.

type ClientConfig 

type ClientConfig struct {
	// Token is the Linear API key or OAuth access token for authentication.
	Token string
	// UseBearer prefixes the Authorization header with "Bearer " (OAuth tokens).
	// Personal API keys must leave this false.
	UseBearer bool
	// OnUnauthorized optionally refreshes credentials after a 401 and retries once.
	OnUnauthorized func(ctx context.Context) (string, error)
	// Endpoint is the GraphQL API endpoint (defaults to Linear's production endpoint).
	Endpoint string
	// HTTPClient is an optional custom HTTP client (useful for testing).
	HTTPClient *http.Client
	// Timeout is the HTTP request timeout (defaults to 30s).
	Timeout time.Duration
}

ClientConfig contains configuration for creating a new Linear API client.

type Comment 

type Comment struct {
	ID        string
	Body      string
	CreatedAt time.Time
	UpdatedAt time.Time
	Author    User
	IssueID   string
}

Comment represents a comment on a Linear issue.

type CommentCreateInput added in v0.2.0 

type CommentCreateInput map[string]interface{}

CommentCreateInput is a custom scalar type for Linear's CommentCreateInput. The Go type name must match the GraphQL type name exactly.

func (CommentCreateInput) GetGraphQLType added in v0.2.0 

func (CommentCreateInput) GetGraphQLType() string

GetGraphQLType returns the GraphQL type name for the input.

func (CommentCreateInput) MarshalJSON added in v0.2.0 

func (c CommentCreateInput) MarshalJSON() ([]byte, error)

MarshalJSON implements json.Marshaler for CommentCreateInput.

type CreateCommentInput 

type CreateCommentInput struct {
	IssueID string
	Body    string
}

CreateCommentInput contains input for creating a new comment.

type CreateIssueInput 

type CreateIssueInput struct {
	TeamID      string
	Title       string
	Description string
	ProjectID   string
	StateID     string
	CycleID     string
	AssigneeID  string
	Priority    int
	ParentID    string // Parent issue ID (empty for top-level issues)
}

CreateIssueInput contains input for creating a new issue.

type CreateIssueRelationInput added in v0.8.0 

type CreateIssueRelationInput struct {
	IssueID        string
	RelatedIssueID string
	Type           IssueRelationType
}

CreateIssueRelationInput contains input for creating an issue relation.

type Cycle added in v0.8.0 

type Cycle struct {
	ID          string
	Name        string
	Number      int
	StartsAt    time.Time
	EndsAt      time.Time
	IsActive    bool
	IsFuture    bool
	IsPast      bool
	IsNext      bool
	IsPrevious  bool
	Description string
	TeamID      string
	CreatedAt   time.Time
	UpdatedAt   time.Time
}

Cycle represents a Linear cycle.

func (Cycle) DisplayName added in v0.8.0 

func (c Cycle) DisplayName() string

DisplayName returns the user-facing cycle name, falling back to the cycle number.

type CycleRef added in v0.8.0 

type CycleRef struct {
	ID         string
	Name       string
	Number     int
	StartsAt   time.Time
	EndsAt     time.Time
	IsActive   bool
	IsFuture   bool
	IsPast     bool
	IsNext     bool
	IsPrevious bool
}

CycleRef represents a lightweight reference to a Linear cycle.

func (CycleRef) DisplayName added in v0.8.0 

func (c CycleRef) DisplayName() string

DisplayName returns the user-facing cycle name, falling back to the cycle number.

type DateFilter added in v0.8.0 

type DateFilter struct {
	Eq   string
	GT   string
	GTE  string
	LT   string
	LTE  string
	Null *bool
}

DateFilter describes a Linear timeless date filter.

func (DateFilter) Empty added in v0.8.0 

func (f DateFilter) Empty() bool

Empty returns whether no date filter fields are set.

type FetchIssuesParams 

type FetchIssuesParams struct {
	TeamID             string
	ProjectID          string
	StateID            string
	CycleID            string
	AssigneeID         string
	LabelIDs           []string
	ProjectMilestoneID string
	DueDate            DateFilter
	Estimate           NumberFilter
	Search             string
	// OrderBy specifies the sort order. Valid API values are "updatedAt" and "createdAt".
	// "priority" is also supported and will be sorted client-side after fetching.
	OrderBy string
	First   int
	// OnProgress is an optional callback invoked after each page is fetched.
	OnProgress func(IssueFetchProgress)
}

FetchIssuesParams contains parameters for fetching issues.

type Issue 

type Issue struct {
	ID               string
	Identifier       string
	Title            string
	Description      string
	State            string
	StateID          string
	Assignee         string
	AssigneeID       string
	Priority         int
	UpdatedAt        time.Time
	CreatedAt        time.Time
	TeamID           string
	ProjectID        string
	Cycle            *CycleRef
	DueDate          *string
	Estimate         *float64
	ProjectMilestone *ProjectMilestoneRef
	URL              string
	Archived         bool
	Labels           []IssueLabel
	Parent           *IssueRef       // Parent issue reference (nil if top-level)
	Children         []IssueChildRef // Child/sub-issue references
	Comments         []Comment       // Comments on this issue
	Relations        []IssueRelation
	Subscribers      []User
	Attachments      []Attachment
}

Issue represents a Linear issue.

type IssueChildRef 

type IssueChildRef struct {
	ID         string
	Identifier string
	Title      string
	State      string
	StateID    string
}

IssueChildRef represents a lightweight reference to a child issue.

type IssueCreateInput 

type IssueCreateInput map[string]interface{}

IssueCreateInput is a custom scalar type for Linear's IssueCreateInput. The Go type name must match the GraphQL type name exactly.

func (IssueCreateInput) GetGraphQLType 

func (IssueCreateInput) GetGraphQLType() string

GetGraphQLType returns the GraphQL type name for the input.

func (IssueCreateInput) MarshalJSON 

func (i IssueCreateInput) MarshalJSON() ([]byte, error)

MarshalJSON implements json.Marshaler for IssueCreateInput.

type IssueFetchProgress added in v0.4.0 

type IssueFetchProgress struct {
	Page    int
	Fetched int
}

IssueFetchProgress describes progress for a paginated issue fetch.

type IssueFilter 

type IssueFilter map[string]interface{}

IssueFilter is a custom scalar type for Linear's IssueFilter input. It allows passing complex filter objects to the GraphQL API.

func (IssueFilter) GetGraphQLType 

func (IssueFilter) GetGraphQLType() string

GetGraphQLType returns the GraphQL type name for the filter.

func (IssueFilter) MarshalJSON 

func (f IssueFilter) MarshalJSON() ([]byte, error)

MarshalJSON implements json.Marshaler for IssueFilter.

type IssueLabel 

type IssueLabel struct {
	ID    string
	Name  string
	Color string // Hex color code (e.g., "#ff0000")
}

IssueLabel represents a label that can be applied to issues.

type IssuePage added in v0.6.0 

type IssuePage struct {
	Issues    []Issue
	HasNext   bool
	EndCursor *string
}

IssuePage represents a single page of issues with pagination info.

type IssueRef 

type IssueRef struct {
	ID         string
	Identifier string
	Title      string
}

IssueRef represents a lightweight reference to an issue (for parent relationships).

type IssueRelation added in v0.8.0 

type IssueRelation struct {
	ID           string
	Type         string
	Issue        IssueRef
	RelatedIssue IssueRef
	Inverse      bool
}

IssueRelation represents a Linear issue relation.

func (IssueRelation) DisplayType added in v0.8.0 

func (r IssueRelation) DisplayType() string

DisplayType returns the relation label from the selected issue's perspective.

type IssueRelationCreateInput added in v0.8.0 

type IssueRelationCreateInput map[string]interface{}

IssueRelationCreateInput is a custom scalar type for Linear's IssueRelationCreateInput.

func (IssueRelationCreateInput) GetGraphQLType added in v0.8.0 

func (IssueRelationCreateInput) GetGraphQLType() string

GetGraphQLType returns the GraphQL type name for the input.

func (IssueRelationCreateInput) MarshalJSON added in v0.8.0 

func (i IssueRelationCreateInput) MarshalJSON() ([]byte, error)

MarshalJSON implements json.Marshaler for IssueRelationCreateInput.

type IssueRelationType added in v0.8.0 

type IssueRelationType string

IssueRelationType is Linear's issue relation enum. 

const (
	IssueRelationBlocks    IssueRelationType = "blocks"
	IssueRelationRelated   IssueRelationType = "related"
	IssueRelationDuplicate IssueRelationType = "duplicate"
	IssueRelationSimilar   IssueRelationType = "similar"
)

func (IssueRelationType) GetGraphQLType added in v0.8.0 

func (IssueRelationType) GetGraphQLType() string

GetGraphQLType returns the GraphQL type name for the enum.

type IssueUpdateInput 

type IssueUpdateInput map[string]interface{}

IssueUpdateInput is a custom scalar type for Linear's IssueUpdateInput. The Go type name must match the GraphQL type name exactly.

func (IssueUpdateInput) GetGraphQLType 

func (IssueUpdateInput) GetGraphQLType() string

GetGraphQLType returns the GraphQL type name for the input.

func (IssueUpdateInput) MarshalJSON 

func (i IssueUpdateInput) MarshalJSON() ([]byte, error)

MarshalJSON implements json.Marshaler for IssueUpdateInput.

type NumberFilter added in v0.8.0 

type NumberFilter struct {
	Eq   *float64
	GT   *float64
	GTE  *float64
	LT   *float64
	LTE  *float64
	Null *bool
}

NumberFilter describes a Linear numeric filter.

func (NumberFilter) Empty added in v0.8.0 

func (f NumberFilter) Empty() bool

Empty returns whether no numeric filter fields are set.

type PaginationOrderBy 

type PaginationOrderBy string

PaginationOrderBy is a custom type for Linear's PaginationOrderBy enum. Valid values are "createdAt" and "updatedAt". 

const (
	OrderByCreatedAt PaginationOrderBy = "createdAt"
	OrderByUpdatedAt PaginationOrderBy = "updatedAt"
)

Common PaginationOrderBy values.

func (PaginationOrderBy) GetGraphQLType 

func (PaginationOrderBy) GetGraphQLType() string

GetGraphQLType returns the GraphQL type name for the enum.

type Project 

type Project struct {
	ID     string
	Name   string
	TeamID string
}

Project represents a Linear project.

type ProjectMilestone added in v0.8.0 

type ProjectMilestone = ProjectMilestoneRef

ProjectMilestone represents a Linear project milestone.

type ProjectMilestoneFilter added in v0.8.0 

type ProjectMilestoneFilter map[string]interface{}

ProjectMilestoneFilter is a custom scalar type for Linear's ProjectMilestoneFilter input.

func (ProjectMilestoneFilter) GetGraphQLType added in v0.8.0 

func (ProjectMilestoneFilter) GetGraphQLType() string

GetGraphQLType returns the GraphQL type name for the filter.

func (ProjectMilestoneFilter) MarshalJSON added in v0.8.0 

func (f ProjectMilestoneFilter) MarshalJSON() ([]byte, error)

MarshalJSON implements json.Marshaler for ProjectMilestoneFilter.

type ProjectMilestoneRef added in v0.8.0 

type ProjectMilestoneRef struct {
	ID         string
	Name       string
	ProjectID  string
	TargetDate *string
	Status     string
	SortOrder  float64
	Progress   float64
}

ProjectMilestoneRef represents a lightweight reference to a Linear project milestone.

type Team 

type Team struct {
	ID   string
	Key  string
	Name string
}

Team represents a Linear team.

type UpdateIssueInput 

type UpdateIssueInput struct {
	ID                 string
	Title              *string
	Description        *string
	StateID            *string
	CycleID            *string // nil = no change, empty string = clear cycle, non-empty = set cycle
	AssigneeID         *string
	Priority           *int
	LabelIDs           *[]string // nil = no change, empty slice = clear all, non-empty = set labels
	ParentID           *string   // nil = no change, empty string = clear parent, non-empty = set parent
	DueDate            *string   // nil = no change, empty string = clear due date, non-empty = set YYYY-MM-DD date
	Estimate           *float64  // nil = no change, non-nil = set estimate
	ClearEstimate      bool      // true = clear estimate
	ProjectMilestoneID *string   // nil = no change, empty string = clear milestone, non-empty = set milestone
}

UpdateIssueInput contains input for updating an issue.

type User 

type User struct {
	ID          string
	Name        string
	DisplayName string
	Email       string
	IsMe        bool
}

User represents a Linear user.

type WorkflowState 

type WorkflowState struct {
	ID       string
	Name     string
	Type     string // backlog, unstarted, started, completed, canceled
	Position float64
	TeamID   string
}

WorkflowState represents a workflow state in a Linear team.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.