forges

type AddCollaboratorOpts struct {
	Permission string // pull, push, admin (GitHub/Gitea); guest, reporter, developer, maintainer, owner (GitLab)
}

type ArchivedFilter int

type Branch struct {
	Name      string `json:"name"`
	SHA       string `json:"sha"`
	Protected bool   `json:"protected"`
	Default   bool   `json:"default"`
}

type BranchService interface {
	List(ctx context.Context, owner, repo string, opts ListBranchOpts) ([]Branch, error)
	Create(ctx context.Context, owner, repo, name, from string) (*Branch, error)
	Delete(ctx context.Context, owner, repo, name string) error
}

type CIJob struct {
	ID         int64      `json:"id"`
	Name       string     `json:"name"`
	Status     string     `json:"status"`
	Conclusion string     `json:"conclusion,omitempty"`
	HTMLURL    string     `json:"html_url,omitempty"`
	StartedAt  *time.Time `json:"started_at,omitempty"`
	FinishedAt *time.Time `json:"finished_at,omitempty"`
}

type CIRun struct {
	ID         int64      `json:"id"`
	Title      string     `json:"title"`
	Status     string     `json:"status"`     // queued, running, completed, failed, success, cancelled
	Conclusion string     `json:"conclusion"` // success, failure, cancelled, skipped (GitHub-specific)
	Branch     string     `json:"branch"`
	SHA        string     `json:"sha"`
	Event      string     `json:"event,omitempty"` // push, pull_request, etc.
	Author     User       `json:"author"`
	HTMLURL    string     `json:"html_url"`
	Jobs       []CIJob    `json:"jobs,omitempty"`
	CreatedAt  time.Time  `json:"created_at"`
	UpdatedAt  time.Time  `json:"updated_at"`
	FinishedAt *time.Time `json:"finished_at,omitempty"`
}

type CIService interface {
	ListRuns(ctx context.Context, owner, repo string, opts ListCIRunOpts) ([]CIRun, error)
	GetRun(ctx context.Context, owner, repo string, runID int64) (*CIRun, error)
	TriggerRun(ctx context.Context, owner, repo string, opts TriggerCIRunOpts) error
	CancelRun(ctx context.Context, owner, repo string, runID int64) error
	RetryRun(ctx context.Context, owner, repo string, runID int64) error
	GetJobLog(ctx context.Context, owner, repo string, jobID int64) (io.ReadCloser, error)
}

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

type Collaborator struct {
	Login      string `json:"login"`
	Permission string `json:"permission"` // read, write, admin
}

type CollaboratorService interface {
	List(ctx context.Context, owner, repo string, opts ListCollaboratorOpts) ([]Collaborator, error)
	Add(ctx context.Context, owner, repo, username string, opts AddCollaboratorOpts) error
	Remove(ctx context.Context, owner, repo, username string) error
}

type Comment struct {
	ID        int64     `json:"id"`
	Body      string    `json:"body"`
	Author    User      `json:"author"`
	HTMLURL   string    `json:"html_url"`
	CreatedAt time.Time `json:"created_at"`
	UpdatedAt time.Time `json:"updated_at"`
}

type CommitStatus struct {
	State       string    `json:"state"`       // success, failure, pending, error
	Context     string    `json:"context"`     // e.g. "my-check"
	Description string    `json:"description"` // short summary
	TargetURL   string    `json:"target_url"`  // link to details
	Creator     string    `json:"creator"`     // login of who created it
	CreatedAt   time.Time `json:"created_at"`
}

type CommitStatusService interface {
	List(ctx context.Context, owner, repo, sha string) ([]CommitStatus, error)
	Set(ctx context.Context, owner, repo, sha string, opts SetCommitStatusOpts) (*CommitStatus, error)
}

type Contributor struct {
	Login         string `json:"login"`
	Contributions int    `json:"contributions"`
	Email         string `json:"email,omitempty"`
	Name          string `json:"name,omitempty"`
}

type CreateDeployKeyOpts struct {
	Title    string
	Key      string
	ReadOnly bool
}

type CreateIssueOpts struct {
	Title     string
	Body      string
	Assignees []string
	Labels    []string
	Milestone string
}

type CreateLabelOpts struct {
	Name        string
	Color       string
	Description string
}

type CreateMilestoneOpts struct {
	Title       string
	Description string
	DueDate     *time.Time
}

type CreatePROpts struct {
	Title     string
	Body      string
	Head      string // source branch
	Base      string // target branch
	Draft     bool
	Assignees []string
	Labels    []string
	Milestone string
	Reviewers []string
}

type CreateReleaseOpts struct {
	TagName       string
	Target        string
	Title         string
	Body          string
	Draft         bool
	Prerelease    bool
	GenerateNotes bool
}

type CreateRepoOpts struct {
	Name          string
	Description   string
	Visibility    Visibility
	Init          bool
	DefaultBranch string
	Readme        bool
	Gitignore     string
	License       string
	Owner         string // org or group; empty = authenticated user
}

type DeployKey struct {
	ID        int64     `json:"id"`
	Title     string    `json:"title"`
	Key       string    `json:"key"`
	ReadOnly  bool      `json:"read_only"`
	CreatedAt time.Time `json:"created_at"`
}

type DeployKeyService interface {
	List(ctx context.Context, owner, repo string, opts ListDeployKeyOpts) ([]DeployKey, error)
	Get(ctx context.Context, owner, repo string, id int64) (*DeployKey, error)
	Create(ctx context.Context, owner, repo string, opts CreateDeployKeyOpts) (*DeployKey, error)
	Delete(ctx context.Context, owner, repo string, id int64) error
}

type EditRepoOpts struct {
	Description   *string
	Homepage      *string
	Visibility    Visibility
	DefaultBranch *string
	HasIssues     *bool
	HasPRs        *bool
}

type FileContent struct {
	Name    string `json:"name"`
	Path    string `json:"path"`
	Content []byte `json:"content"`
	SHA     string `json:"sha,omitempty"`
}

type FileEntry struct {
	Name string `json:"name"`
	Path string `json:"path"`
	Type string `json:"type"` // file, dir, symlink
	Size int64  `json:"size"`
}

type FileService interface {
	Get(ctx context.Context, owner, repo, path, ref string) (*FileContent, error)
	List(ctx context.Context, owner, repo, path, ref string) ([]FileEntry, error)
}

type Forge interface {
	Repos() RepoService
	Issues() IssueService
	PullRequests() PullRequestService
	Labels() LabelService
	Milestones() MilestoneService
	Releases() ReleaseService
	CI() CIService
	Branches() BranchService
	DeployKeys() DeployKeyService
	Secrets() SecretService
	Notifications() NotificationService
	Reviews() ReviewService
	Files() FileService
	Collaborators() CollaboratorService
	CommitStatuses() CommitStatusService
	GetRateLimit(ctx context.Context) (*RateLimit, error)
}

type ForgeBuilders struct {
	GitHub func(baseURL, token string, hc *http.Client) Forge
	GitLab func(baseURL, token string, hc *http.Client) Forge
	Gitea  func(baseURL, token string, hc *http.Client) Forge
}

type ForgeType string

type ForkFilter int

type ForkRepoOpts struct {
	Owner string // target owner/org; empty = authenticated user
	Name  string // new name; empty = keep original
}

type HTTPError struct {
	StatusCode int
	URL        string
	Body       string
}

type Issue struct {
	Number    int        `json:"number"`
	Title     string     `json:"title"`
	Body      string     `json:"body"`
	State     string     `json:"state"` // "open" or "closed"
	Author    User       `json:"author"`
	Assignees []User     `json:"assignees,omitempty"`
	Labels    []Label    `json:"labels,omitempty"`
	Milestone *Milestone `json:"milestone,omitempty"`
	Comments  int        `json:"comments"`
	Locked    bool       `json:"locked"`
	HTMLURL   string     `json:"html_url"`
	CreatedAt time.Time  `json:"created_at"`
	UpdatedAt time.Time  `json:"updated_at"`
	ClosedAt  *time.Time `json:"closed_at,omitempty"`
}

type IssueService interface {
	Get(ctx context.Context, owner, repo string, number int) (*Issue, error)
	List(ctx context.Context, owner, repo string, opts ListIssueOpts) ([]Issue, error)
	Create(ctx context.Context, owner, repo string, opts CreateIssueOpts) (*Issue, error)
	Update(ctx context.Context, owner, repo string, number int, opts UpdateIssueOpts) (*Issue, error)
	Close(ctx context.Context, owner, repo string, number int) error
	Reopen(ctx context.Context, owner, repo string, number int) error
	Delete(ctx context.Context, owner, repo string, number int) error
	CreateComment(ctx context.Context, owner, repo string, number int, body string) (*Comment, error)
	ListComments(ctx context.Context, owner, repo string, number int) ([]Comment, error)
	ListReactions(ctx context.Context, owner, repo string, number int, commentID int64) ([]Reaction, error)
	AddReaction(ctx context.Context, owner, repo string, number int, commentID int64, reaction string) (*Reaction, error)
}

type Label struct {
	Name        string `json:"name"`
	Color       string `json:"color,omitempty"`
	Description string `json:"description,omitempty"`
}

type LabelService interface {
	List(ctx context.Context, owner, repo string, opts ListLabelOpts) ([]Label, error)
	Get(ctx context.Context, owner, repo, name string) (*Label, error)
	Create(ctx context.Context, owner, repo string, opts CreateLabelOpts) (*Label, error)
	Update(ctx context.Context, owner, repo, name string, opts UpdateLabelOpts) (*Label, error)
	Delete(ctx context.Context, owner, repo, name string) error
}

type ListBranchOpts struct {
	Limit   int // max total results; 0 = unlimited
	Page    int // starting page; 0 or 1 = first page
	PerPage int // results per API request; 0 = default
}

type ListCIRunOpts struct {
	Branch   string
	Status   string
	User     string
	Workflow string
	Limit    int // max total results; 0 = unlimited
	Page     int // starting page; 0 or 1 = first page
	PerPage  int // results per API request; 0 = default
}

type ListCollaboratorOpts struct {
	Limit   int // max total results; 0 = unlimited
	Page    int // starting page; 0 or 1 = first page
	PerPage int // results per API request; 0 = default
}

type ListDeployKeyOpts struct {
	Limit   int // max total results; 0 = unlimited
	Page    int // starting page; 0 or 1 = first page
	PerPage int // results per API request; 0 = default
}

type ListForksOpts struct {
	Sort    string // newest, oldest, stargazers, watchers
	Limit   int    // max total results; 0 = unlimited
	Page    int    // starting page; 0 or 1 = first page
	PerPage int    // results per API request; 0 = default
}

type ListIssueOpts struct {
	State    string // open, closed, all
	Labels   []string
	Assignee string
	Author   string
	Sort     string
	Order    string
	Limit    int // max total results; 0 = unlimited
	Page     int // starting page; 0 or 1 = first page
	PerPage  int // results per API request; 0 = default
}

type ListLabelOpts struct {
	Limit   int // max total results; 0 = unlimited
	Page    int // starting page; 0 or 1 = first page
	PerPage int // results per API request; 0 = default
}

type ListMilestoneOpts struct {
	State   string // open, closed, all
	Limit   int    // max total results; 0 = unlimited
	Page    int    // starting page; 0 or 1 = first page
	PerPage int    // results per API request; 0 = default
}

type ListNotificationOpts struct {
	Repo    string // filter by repo (owner/repo)
	Unread  bool   // only unread
	Limit   int    // max total results; 0 = unlimited
	Page    int    // starting page; 0 or 1 = first page
	PerPage int    // results per API request; 0 = default
}

type ListPROpts struct {
	State    string // open, closed, merged, all
	Labels   []string
	Assignee string
	Author   string
	Base     string
	Head     string
	Sort     string
	Order    string
	Limit    int // max total results; 0 = unlimited
	Page     int // starting page; 0 or 1 = first page
	PerPage  int // results per API request; 0 = default
}

type ListReleaseOpts struct {
	Limit   int // max total results; 0 = unlimited
	Page    int // starting page; 0 or 1 = first page
	PerPage int // results per API request; 0 = default
}

type ListRepoOpts struct {
	Archived ArchivedFilter
	Forks    ForkFilter
	Sort     string
	Order    string
	Limit    int // max total results; 0 = unlimited
	Page     int // starting page; 0 or 1 = first page
	PerPage  int // results per API request; 0 = default
}

type ListReviewOpts struct {
	Limit   int // max total results; 0 = unlimited
	Page    int // starting page; 0 or 1 = first page
	PerPage int // results per API request; 0 = default
}

type ListSecretOpts struct {
	Limit   int // max total results; 0 = unlimited
	Page    int // starting page; 0 or 1 = first page
	PerPage int // results per API request; 0 = default
}

type MarkNotificationOpts struct {
	ID   string // mark a single thread; empty = mark all
	Repo string // mark all in a repo; empty = mark all
}

type MergePROpts struct {
	Method  string // merge, squash, rebase
	Title   string // commit title
	Message string // commit message
	Delete  bool   // delete branch after merge
}

type Milestone struct {
	Title       string     `json:"title"`
	Number      int        `json:"number"`
	Description string     `json:"description,omitempty"`
	State       string     `json:"state"`
	DueDate     *time.Time `json:"due_date,omitempty"`
}

type MilestoneService interface {
	List(ctx context.Context, owner, repo string, opts ListMilestoneOpts) ([]Milestone, error)
	Get(ctx context.Context, owner, repo string, id int) (*Milestone, error)
	Create(ctx context.Context, owner, repo string, opts CreateMilestoneOpts) (*Milestone, error)
	Update(ctx context.Context, owner, repo string, id int, opts UpdateMilestoneOpts) (*Milestone, error)
	Close(ctx context.Context, owner, repo string, id int) error
	Reopen(ctx context.Context, owner, repo string, id int) error
	Delete(ctx context.Context, owner, repo string, id int) error
}

type Notification struct {
	ID          string                  `json:"id"`
	Title       string                  `json:"title"`
	SubjectType NotificationSubjectType `json:"subject_type"`
	Repo        string                  `json:"repo"`
	Unread      bool                    `json:"unread"`
	Reason      string                  `json:"reason,omitempty"`
	URL         string                  `json:"url,omitempty"`
	UpdatedAt   time.Time               `json:"updated_at"`
}

type NotificationService interface {
	List(ctx context.Context, opts ListNotificationOpts) ([]Notification, error)
	MarkRead(ctx context.Context, opts MarkNotificationOpts) error
	Get(ctx context.Context, id string) (*Notification, error)
}

type NotificationSubjectType string

type Option func(*Client)

type PullRequest struct {
	Number       int        `json:"number"`
	Title        string     `json:"title"`
	Body         string     `json:"body"`
	State        string     `json:"state"` // "open", "closed", or "merged"
	Draft        bool       `json:"draft"`
	Author       User       `json:"author"`
	Assignees    []User     `json:"assignees,omitempty"`
	Reviewers    []User     `json:"reviewers,omitempty"`
	Labels       []Label    `json:"labels,omitempty"`
	Milestone    *Milestone `json:"milestone,omitempty"`
	Head         string     `json:"head"` // head branch
	Base         string     `json:"base"` // base branch
	Mergeable    bool       `json:"mergeable"`
	Merged       bool       `json:"merged"`
	MergedBy     *User      `json:"merged_by,omitempty"`
	Comments     int        `json:"comments"`
	Additions    int        `json:"additions"`
	Deletions    int        `json:"deletions"`
	ChangedFiles int        `json:"changed_files"`
	HTMLURL      string     `json:"html_url"`
	DiffURL      string     `json:"diff_url,omitempty"`
	CreatedAt    time.Time  `json:"created_at"`
	UpdatedAt    time.Time  `json:"updated_at"`
	MergedAt     *time.Time `json:"merged_at,omitempty"`
	ClosedAt     *time.Time `json:"closed_at,omitempty"`
}

type PullRequestService interface {
	Get(ctx context.Context, owner, repo string, number int) (*PullRequest, error)
	List(ctx context.Context, owner, repo string, opts ListPROpts) ([]PullRequest, error)
	Create(ctx context.Context, owner, repo string, opts CreatePROpts) (*PullRequest, error)
	Update(ctx context.Context, owner, repo string, number int, opts UpdatePROpts) (*PullRequest, error)
	Close(ctx context.Context, owner, repo string, number int) error
	Reopen(ctx context.Context, owner, repo string, number int) error
	Merge(ctx context.Context, owner, repo string, number int, opts MergePROpts) error
	Diff(ctx context.Context, owner, repo string, number int) (string, error)
	CreateComment(ctx context.Context, owner, repo string, number int, body string) (*Comment, error)
	ListComments(ctx context.Context, owner, repo string, number int) ([]Comment, error)
	ListReactions(ctx context.Context, owner, repo string, number int, commentID int64) ([]Reaction, error)
	AddReaction(ctx context.Context, owner, repo string, number int, commentID int64, reaction string) (*Reaction, error)
}

type RateLimit struct {
	Limit     int       `json:"limit"`
	Remaining int       `json:"remaining"`
	Reset     time.Time `json:"reset"`
}

type Reaction struct {
	ID      int64  `json:"id"`
	User    string `json:"user"`
	Content string `json:"content"` // +1, -1, laugh, hooray, confused, heart, rocket, eyes
}

type Release struct {
	TagName     string         `json:"tag_name"`
	Title       string         `json:"title"`
	Body        string         `json:"body,omitempty"`
	Draft       bool           `json:"draft"`
	Prerelease  bool           `json:"prerelease"`
	Target      string         `json:"target,omitempty"`
	Author      User           `json:"author"`
	Assets      []ReleaseAsset `json:"assets,omitempty"`
	TarballURL  string         `json:"tarball_url,omitempty"`
	ZipballURL  string         `json:"zipball_url,omitempty"`
	HTMLURL     string         `json:"html_url"`
	CreatedAt   time.Time      `json:"created_at"`
	PublishedAt time.Time      `json:"published_at,omitzero"`
}

type ReleaseAsset struct {
	ID            int64     `json:"id"`
	Name          string    `json:"name"`
	Size          int       `json:"size"`
	DownloadCount int       `json:"download_count"`
	DownloadURL   string    `json:"download_url"`
	CreatedAt     time.Time `json:"created_at"`
}

type ReleaseService interface {
	List(ctx context.Context, owner, repo string, opts ListReleaseOpts) ([]Release, error)
	Get(ctx context.Context, owner, repo, tag string) (*Release, error)
	GetLatest(ctx context.Context, owner, repo string) (*Release, error)
	Create(ctx context.Context, owner, repo string, opts CreateReleaseOpts) (*Release, error)
	Update(ctx context.Context, owner, repo, tag string, opts UpdateReleaseOpts) (*Release, error)
	Delete(ctx context.Context, owner, repo, tag string) error
	UploadAsset(ctx context.Context, owner, repo, tag string, file *os.File) (*ReleaseAsset, error)
	DownloadAsset(ctx context.Context, owner, repo string, assetID int64) (io.ReadCloser, error)
}

type RepoService interface {
	Get(ctx context.Context, owner, repo string) (*Repository, error)
	List(ctx context.Context, owner string, opts ListRepoOpts) ([]Repository, error)
	Create(ctx context.Context, opts CreateRepoOpts) (*Repository, error)
	Edit(ctx context.Context, owner, repo string, opts EditRepoOpts) (*Repository, error)
	Delete(ctx context.Context, owner, repo string) error
	Fork(ctx context.Context, owner, repo string, opts ForkRepoOpts) (*Repository, error)
	ListForks(ctx context.Context, owner, repo string, opts ListForksOpts) ([]Repository, error)
	ListTags(ctx context.Context, owner, repo string) ([]Tag, error)
	ListContributors(ctx context.Context, owner, repo string) ([]Contributor, error)
	Search(ctx context.Context, opts SearchRepoOpts) ([]Repository, error)
}

type Repository struct {
	FullName            string    `json:"full_name"`
	Owner               string    `json:"owner"`
	Name                string    `json:"name"`
	Description         string    `json:"description,omitempty"`
	Homepage            string    `json:"homepage,omitempty"`
	HTMLURL             string    `json:"html_url"`
	CloneURL            string    `json:"clone_url,omitempty"`
	SSHURL              string    `json:"ssh_url,omitempty"`
	Language            string    `json:"language,omitempty"`
	License             string    `json:"license,omitempty"` // SPDX identifier
	DefaultBranch       string    `json:"default_branch,omitempty"`
	Fork                bool      `json:"fork"`
	Archived            bool      `json:"archived"`
	Private             bool      `json:"private"`
	MirrorURL           string    `json:"mirror_url,omitempty"`
	SourceName          string    `json:"source_name,omitempty"` // fork parent full name
	Size                int       `json:"size"`
	StargazersCount     int       `json:"stargazers_count"`
	ForksCount          int       `json:"forks_count"`
	OpenIssuesCount     int       `json:"open_issues_count"`
	SubscribersCount    int       `json:"subscribers_count"`
	HasIssues           bool      `json:"has_issues"`
	PullRequestsEnabled bool      `json:"pull_requests_enabled"`
	Topics              []string  `json:"topics,omitempty"`
	LogoURL             string    `json:"logo_url,omitempty"`
	CreatedAt           time.Time `json:"created_at"`
	UpdatedAt           time.Time `json:"updated_at"`
	PushedAt            time.Time `json:"pushed_at,omitzero"`
}

type Review struct {
	ID          int64       `json:"id"`
	State       ReviewState `json:"state"`
	Body        string      `json:"body,omitempty"`
	Author      User        `json:"author"`
	HTMLURL     string      `json:"html_url,omitempty"`
	SubmittedAt time.Time   `json:"submitted_at,omitzero"`
}

type ReviewService interface {
	List(ctx context.Context, owner, repo string, number int, opts ListReviewOpts) ([]Review, error)
	Submit(ctx context.Context, owner, repo string, number int, opts SubmitReviewOpts) (*Review, error)
	RequestReviewers(ctx context.Context, owner, repo string, number int, users []string) error
	RemoveReviewers(ctx context.Context, owner, repo string, number int, users []string) error
}

type ReviewState string

type SearchRepoOpts struct {
	Query   string
	Sort    string
	Order   string
	Limit   int // max total results; 0 = unlimited
	Page    int // starting page; 0 or 1 = first page
	PerPage int // results per API request; 0 = default
}

type Secret struct {
	Name      string    `json:"name"`
	CreatedAt time.Time `json:"created_at,omitzero"`
	UpdatedAt time.Time `json:"updated_at,omitzero"`
}

type SecretService interface {
	List(ctx context.Context, owner, repo string, opts ListSecretOpts) ([]Secret, error)
	Set(ctx context.Context, owner, repo string, opts SetSecretOpts) error
	Delete(ctx context.Context, owner, repo, name string) error
}

type SetCommitStatusOpts struct {
	State       string // success, failure, pending, error
	Context     string // e.g. "my-check"
	Description string
	TargetURL   string
}

type SetSecretOpts struct {
	Name  string
	Value string
}

type SubmitReviewOpts struct {
	State ReviewState // approved, changes_requested, or commented
	Body  string
}

type Tag struct {
	Name   string `json:"name"`
	Commit string `json:"commit"` // SHA
}

type TriggerCIRunOpts struct {
	Workflow string
	Branch   string
	Inputs   map[string]string
}

type UpdateIssueOpts struct {
	Title     *string
	Body      *string
	Assignees []string
	Labels    []string
	Milestone *string
}

type UpdateLabelOpts struct {
	Name        *string
	Color       *string
	Description *string
}

type UpdateMilestoneOpts struct {
	Title       *string
	Description *string
	State       *string
	DueDate     *time.Time
}

type UpdatePROpts struct {
	Title     *string
	Body      *string
	Base      *string
	Assignees []string
	Labels    []string
	Milestone *string
	Reviewers []string
}

type UpdateReleaseOpts struct {
	TagName    *string
	Target     *string
	Title      *string
	Body       *string
	Draft      *bool
	Prerelease *bool
}

type User struct {
	Login     string `json:"login"`
	Name      string `json:"name,omitempty"`
	Email     string `json:"email,omitempty"`
	AvatarURL string `json:"avatar_url,omitempty"`
	HTMLURL   string `json:"html_url,omitempty"`
	IsOrg     bool   `json:"is_org,omitempty"`
}

type Visibility int