client

package
v0.15.0 Latest Latest
Warning

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

 Go to latest Published: May 1, 2026 License: MIT Imports: 10 Imported by: 0

Documentation

Overview

Package client provides an HTTP API client for the arc server. It wraps REST endpoints for projects, issues, plans, and workspace paths.

Label client methods for global label CRUD and issue-label associations. Labels are global resources (not project-scoped); issue-label endpoints require a project ID for workspace validation.

Share keyring client methods — wrap the /api/v1/shares endpoints used by arc share commands to read/write the author's local keyring.

Index

Constants

This section is empty.

Variables

View Source 
var ErrShareNotFound = errors.New("share not found")

ErrShareNotFound is returned by GetShare when the keyring has no entry for the given ID. Callers can use errors.Is to branch on this.

Functions

This section is empty.

Types

type AISessionResponse added in v0.13.0 

type AISessionResponse struct {
	types.AISession
	Agents []*types.AIAgent `json:"agents"`
}

AISessionResponse extends AISession with its agents for detail views. Used by GetAISession to return the session along with all registered agents.

type Client 

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

Client is the HTTP API client for the arc issue tracking server. It provides methods for all CRUD operations on projects, issues, dependencies, labels, plans, and comments.

func New 

func New(baseURL string) *Client

New creates a new API client configured to connect to the given base URL. The client defaults to a 30-second timeout and "cli" as the actor identity.

func (*Client) AddDependency 

func (c *Client) AddDependency(projID, issueID, dependsOnID, depType string) error

AddDependency adds a dependency between two issues. depType should be one of: "blocks", "parent-child", "related", "discovered-from".

func (*Client) AddDependencyByID added in v0.13.0 

func (c *Client) AddDependencyByID(issueID, dependsOnID, depType string) error

AddDependencyByID adds a dependency between two issues by globally-unique IDs.

func (*Client) AddLabelToIssue added in v0.13.0 

func (c *Client) AddLabelToIssue(projectID, issueID, label string) error

AddLabelToIssue associates a label with an issue.

func (*Client) AddLabelToIssueByID added in v0.13.0 

func (c *Client) AddLabelToIssueByID(issueID, label string) error

AddLabelToIssueByID associates a label with an issue by its globally-unique ID.

func (*Client) BaseURL added in v0.13.0 

func (c *Client) BaseURL() string

BaseURL returns the server's base URL.

func (*Client) CloseIssue 

func (c *Client) CloseIssue(projID, id, reason string, cascade bool) (*types.Issue, error)

CloseIssue closes an issue. When cascade is true, open children are closed recursively. When cascade is false and the issue has open children, a *types.OpenChildrenError is returned so the caller can prompt the user.

func (*Client) CloseIssueByID added in v0.13.0 

func (c *Client) CloseIssueByID(id, reason string, cascade bool) (*types.Issue, error)

CloseIssueByID closes an issue by its globally-unique ID without requiring project context.

func (*Client) CreateAIAgent added in v0.13.0 

func (c *Client) CreateAIAgent(projectID, sessionID string, agent *types.AIAgent) (*types.AIAgent, error)

CreateAIAgent creates a new AI agent for a session within a project.

func (*Client) CreateAISession added in v0.13.0 

func (c *Client) CreateAISession(projectID string, session *types.AISession) (*types.AISession, error)

CreateAISession creates a new AI session under a project. The operation is idempotent: if a session with the same ID already exists, the existing record is returned.

func (*Client) CreateIssue 

func (c *Client) CreateIssue(projID string, req CreateIssueRequest) (*types.Issue, error)

CreateIssue creates a new issue.

func (*Client) CreateLabel added in v0.13.0 

func (c *Client) CreateLabel(name, color, description string) (*types.Label, error)

CreateLabel creates a new global label.

func (*Client) CreatePlan added in v0.7.0 

func (c *Client) CreatePlan(filePath string) (*types.Plan, error)

CreatePlan registers an ephemeral plan backed by a filesystem markdown file.

func (*Client) CreatePlanComment added in v0.13.0 

func (c *Client) CreatePlanComment(planID string, lineNumber *int, content string) (*types.PlanComment, error)

CreatePlanComment adds a review comment to a plan.

func (*Client) CreateProject added in v0.12.0 

func (c *Client) CreateProject(name, prefix, description string) (*types.Project, error)

CreateProject creates a new project.

func (*Client) CreateWorkspace 

func (c *Client) CreateWorkspace(projID string, req CreateWorkspaceRequest) (*types.Workspace, error)

CreateWorkspace registers a new workspace (directory path) for a project.

func (*Client) DeleteAISession added in v0.13.0 

func (c *Client) DeleteAISession(projectID, id string) error

DeleteAISession deletes an AI session by ID within a project.

func (*Client) DeleteIssue 

func (c *Client) DeleteIssue(projID, id string) error

DeleteIssue deletes an issue.

func (*Client) DeleteLabel added in v0.13.0 

func (c *Client) DeleteLabel(name string) error

DeleteLabel deletes a global label.

func (*Client) DeletePlan added in v0.7.0 

func (c *Client) DeletePlan(planID string) error

DeletePlan deletes a plan and its comments.

func (*Client) DeleteProject added in v0.12.0 

func (c *Client) DeleteProject(id string) error

DeleteProject deletes a project.

func (*Client) DeleteShare added in v0.13.0 

func (c *Client) DeleteShare(id string) error

DeleteShare removes a keyring entry. Idempotent: no error if absent.

func (*Client) DeleteWorkspace 

func (c *Client) DeleteWorkspace(projID, wsID string) error

DeleteWorkspace removes a workspace (directory path) from a project.

func (*Client) GetAIAgent added in v0.13.0 

func (c *Client) GetAIAgent(projectID, sessionID, agentID string) (*types.AIAgent, error)

GetAIAgent retrieves a single agent by ID within a project and session.

func (*Client) GetAISession added in v0.13.0 

func (c *Client) GetAISession(projectID, id string) (*AISessionResponse, error)

GetAISession retrieves an AI session by ID within a project. The response includes the Agents field.

func (*Client) GetAgentTranscript added in v0.13.0 

func (c *Client) GetAgentTranscript(projectID, sessionID, agentID string) ([]map[string]any, error)

GetAgentTranscript retrieves the transcript for an agent as a slice of JSON objects. The transcript is read from the agent's JSONL file on the server.

func (*Client) GetBlockedIssues 

func (c *Client) GetBlockedIssues(projID string, limit int) ([]*types.BlockedIssue, error)

GetBlockedIssues returns blocked issues.

func (*Client) GetIssue 

func (c *Client) GetIssue(projID, id string) (*types.Issue, error)

GetIssue retrieves an issue by ID.

func (*Client) GetIssueByID added in v0.13.0 

func (c *Client) GetIssueByID(id string) (*types.Issue, error)

GetIssueByID retrieves an issue by its globally-unique ID without requiring project context.

func (*Client) GetIssueDetails 

func (c *Client) GetIssueDetails(projID, id string) (*types.IssueDetails, error)

GetIssueDetails retrieves an issue with all relational data.

func (*Client) GetIssueDetailsByID added in v0.13.0 

func (c *Client) GetIssueDetailsByID(id string) (*types.IssueDetails, error)

GetIssueDetailsByID retrieves an issue with all relational data by its globally-unique ID.

func (*Client) GetPlan added in v0.7.0 

func (c *Client) GetPlan(planID string) (*types.PlanWithContent, error)

GetPlan retrieves a plan by ID, including file content.

func (*Client) GetProject added in v0.12.0 

func (c *Client) GetProject(id string) (*types.Project, error)

GetProject retrieves a project by ID.

func (*Client) GetProjectStats added in v0.12.0 

func (c *Client) GetProjectStats(projID string) (*types.Statistics, error)

GetProjectStats returns project statistics.

func (*Client) GetReadyWork 

func (c *Client) GetReadyWork(projID string, limit int, sortPolicy string) ([]*types.Issue, error)

GetReadyWork returns issues ready to work on. sortPolicy can be: "hybrid" (default), "priority", or "oldest".

func (*Client) GetShare added in v0.13.0 

func (c *Client) GetShare(id string) (*types.Share, error)

GetShare returns the keyring entry for the given share ID. Returns ErrShareNotFound if the ID is not in the keyring.

func (*Client) Health 

func (c *Client) Health() error

Health checks the server health by sending a GET /health request.

func (*Client) ListAIAgents added in v0.13.0 

func (c *Client) ListAIAgents(projectID, sessionID string) ([]*types.AIAgent, error)

ListAIAgents returns all agents for a session within a project.

func (*Client) ListAISessions added in v0.13.0 

func (c *Client) ListAISessions(projectID string, limit, offset int) ([]*types.AISession, error)

ListAISessions returns a paginated list of AI sessions within a project.

func (*Client) ListIssues 

func (c *Client) ListIssues(projID string, opts ListIssuesOptions) ([]*types.Issue, error)

ListIssues returns issues for a project.

func (*Client) ListLabels added in v0.13.0 

func (c *Client) ListLabels() ([]*types.Label, error)

ListLabels returns all global labels.

func (*Client) ListPlanComments added in v0.13.0 

func (c *Client) ListPlanComments(planID string) ([]*types.PlanComment, error)

ListPlanComments returns all comments for a plan.

func (*Client) ListProjects added in v0.12.0 

func (c *Client) ListProjects() ([]*types.Project, error)

ListProjects returns all projects.

func (*Client) ListShares added in v0.13.0 

func (c *Client) ListShares() ([]*types.Share, error)

ListShares returns all keyring entries (newest first).

func (*Client) ListWorkspaces 

func (c *Client) ListWorkspaces(projID string) ([]*types.Workspace, error)

ListWorkspaces returns all workspaces (directory paths) for a project.

func (*Client) MergeProjects added in v0.12.0 

func (c *Client) MergeProjects(targetID string, sourceIDs []string) (*types.MergeResult, error)

MergeProjects merges one or more source projects into a target project.

func (*Client) RemoveDependency 

func (c *Client) RemoveDependency(projID, issueID, dependsOnID string) error

RemoveDependency removes a dependency between two issues.

func (*Client) RemoveDependencyByID added in v0.13.0 

func (c *Client) RemoveDependencyByID(issueID, dependsOnID string) error

RemoveDependencyByID removes a dependency between two issues by globally-unique IDs.

func (*Client) RemoveLabelFromIssue added in v0.13.0 

func (c *Client) RemoveLabelFromIssue(projectID, issueID, label string) error

RemoveLabelFromIssue removes a label association from an issue.

func (*Client) RemoveLabelFromIssueByID added in v0.13.0 

func (c *Client) RemoveLabelFromIssueByID(issueID, label string) error

RemoveLabelFromIssueByID removes a label association from an issue by its globally-unique ID.

func (*Client) ResolveProjectByPath added in v0.12.0 

func (c *Client) ResolveProjectByPath(fsPath string) (*types.ProjectResolution, error)

ResolveProjectByPath finds the project associated with a filesystem path.

func (*Client) SetActor 

func (c *Client) SetActor(actor string)

SetActor sets the actor identity sent via the X-Actor header on all requests.

func (*Client) UpdateIssue 

func (c *Client) UpdateIssue(projID, id string, updates map[string]any) (*types.Issue, error)

UpdateIssue updates an issue.

func (*Client) UpdateIssueByID added in v0.13.0 

func (c *Client) UpdateIssueByID(id string, updates map[string]any) (*types.Issue, error)

UpdateIssueByID updates an issue by its globally-unique ID without requiring project context.

func (*Client) UpdateLabel added in v0.13.0 

func (c *Client) UpdateLabel(name string, fields map[string]string) (*types.Label, error)

UpdateLabel updates a label's color or description. The fields map should contain only the fields that were explicitly set by the caller.

func (*Client) UpdatePlanContent added in v0.13.0 

func (c *Client) UpdatePlanContent(planID string, content string) error

UpdatePlanContent writes new content to the plan's file.

func (*Client) UpdatePlanStatus added in v0.13.0 

func (c *Client) UpdatePlanStatus(planID string, status string) error

UpdatePlanStatus updates the status of a plan.

func (*Client) UpdateProject added in v0.12.0 

func (c *Client) UpdateProject(id string, updates map[string]any) (*types.Project, error)

UpdateProject updates a project.

func (*Client) UpdateWorkspace added in v0.12.0 

func (c *Client) UpdateWorkspace(projID, wsID string, updates map[string]string) (*types.Workspace, error)

UpdateWorkspace updates a workspace's metadata.

func (*Client) UpsertShare added in v0.13.0 

func (c *Client) UpsertShare(share *types.Share) (*types.Share, error)

UpsertShare inserts or replaces a keyring entry. Returns the stored record.

type CreateIssueRequest 

type CreateIssueRequest struct {
	Title       string `json:"title"`
	Description string `json:"description,omitempty"`
	Priority    int    `json:"priority,omitempty"`
	IssueType   string `json:"issue_type,omitempty"`
	Assignee    string `json:"assignee,omitempty"`
	ParentID    string `json:"parent_id,omitempty"` // For hierarchical child IDs
}

CreateIssueRequest is the request for creating an issue.

type CreateWorkspaceRequest added in v0.12.0 

type CreateWorkspaceRequest struct {
	Path      string `json:"path"`
	Label     string `json:"label,omitempty"`
	Hostname  string `json:"hostname,omitempty"`
	GitRemote string `json:"git_remote,omitempty"`
	PathType  string `json:"path_type,omitempty"`
}

CreateWorkspaceRequest is the request for registering a workspace (directory path).

type ListIssuesOptions 

type ListIssuesOptions struct {
	Status   string // Filter by status (e.g., "open", "closed")
	Type     string // Filter by issue type (e.g., "bug", "feature")
	Assignee string // Filter by assignee name
	Query    string // Full-text search in title/description
	Limit    int    // Maximum number of results
	Parent   string // Filter by parent issue ID
}

ListIssuesOptions configures issue listing. All fields are optional; zero values are omitted from the query.

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.