clientv1

type Client interface {

	// GetAuthenticatedUser returns the currently authenticated user.
	GetAuthenticatedUser(ctx context.Context) (*gogithub.User, error)

	// GetUser returns information about a specific user.
	GetUser(ctx context.Context, username string) (*gogithub.User, error)

	// GetRepository retrieves a repository by owner and name.
	GetRepository(ctx context.Context, owner, repo string) (*gogithub.Repository, error)

	// ListUserRepos lists all repositories for a user.
	ListUserRepos(ctx context.Context, user string) ([]*gogithub.Repository, error)

	// ListOrgRepos lists all repositories for an organization.
	ListOrgRepos(ctx context.Context, org string) ([]*gogithub.Repository, error)

	// GetDefaultBranch returns the default branch name for a repository.
	GetDefaultBranch(ctx context.Context, owner, repo string) (string, error)

	// CreateFork creates a fork of a repository.
	CreateFork(ctx context.Context, owner, repo string, opts *CreateForkOptions) (*gogithub.Repository, error)

	// GetFileContent fetches a file's content from a repository.
	GetFileContent(ctx context.Context, owner, repo, path string, opts *gogithub.ContentOptions) ([]byte, error)

	// GetFileContentString fetches a file's content as a string.
	GetFileContentString(ctx context.Context, owner, repo, path string, opts *gogithub.ContentOptions) (string, error)

	// GetFileContentWithSHA fetches a file's content and returns its SHA.
	// Returns the content bytes, the file's SHA, and any error.
	GetFileContentWithSHA(ctx context.Context, owner, repo, path string, opts *gogithub.ContentOptions) ([]byte, string, error)

	// ListDirectory lists files in a directory.
	ListDirectory(ctx context.Context, owner, repo, path string, opts *gogithub.ContentOptions) ([]*gogithub.FileContent, error)

	// FileExists checks if a file exists in a repository.
	FileExists(ctx context.Context, owner, repo, path string, opts *gogithub.ContentOptions) (bool, error)

	// CreateFile creates a new file in a repository.
	CreateFile(ctx context.Context, owner, repo, path string, opts *CreateFileOptions) (*gogithub.CreateFileResult, error)

	// UpdateFile updates an existing file in a repository.
	// Requires the current SHA of the file for optimistic locking.
	UpdateFile(ctx context.Context, owner, repo, path string, opts *UpdateFileOptions) (*gogithub.CreateFileResult, error)

	// DeleteFile deletes a file from a repository.
	// Requires the current SHA of the file.
	DeleteFile(ctx context.Context, owner, repo, path, sha, message string, opts *DeleteFileOptions) (*gogithub.DeleteFileResult, error)

	// GetRef retrieves a git reference by its full name (e.g., "refs/heads/main").
	GetRef(ctx context.Context, owner, repo, ref string) (*gogithub.Reference, error)

	// CreateRef creates a git reference.
	CreateRef(ctx context.Context, owner, repo, ref, sha string) (*gogithub.Reference, error)

	// UpdateRef updates a git reference to point to a new SHA.
	UpdateRef(ctx context.Context, owner, repo, ref, sha string, force bool) (*gogithub.Reference, error)

	// DeleteRef deletes a git reference.
	DeleteRef(ctx context.Context, owner, repo, ref string) error

	// GetBranchSHA returns the commit SHA for a branch.
	GetBranchSHA(ctx context.Context, owner, repo, branch string) (string, error)

	// GetTagSHA returns the commit SHA for a tag.
	GetTagSHA(ctx context.Context, owner, repo, tag string) (string, error)

	// ListBranches lists all branches in a repository.
	ListBranches(ctx context.Context, owner, repo string) ([]*gogithub.Branch, error)

	// ListTags lists all tags in a repository.
	ListTags(ctx context.Context, owner, repo string) ([]*gogithub.Tag, error)

	// CreateTag creates an annotated tag.
	CreateTag(ctx context.Context, owner, repo, tag, sha, message string) error

	// GetCommit retrieves a commit by SHA.
	GetCommit(ctx context.Context, owner, repo, sha string) (*gogithub.Commit, error)

	// ListCommits lists commits in a repository.
	ListCommits(ctx context.Context, owner, repo string, opts *ListCommitsOptions) ([]*gogithub.Commit, error)

	// CreateCommit creates a commit with the given tree and parent.
	CreateCommit(ctx context.Context, owner, repo string, opts *CreateCommitOptions) (*gogithub.Commit, error)

	// GetTree retrieves a git tree by SHA.
	GetTree(ctx context.Context, owner, repo, sha string, recursive bool) ([]*gogithub.TreeNode, error)

	// CreateTree creates a git tree from file entries.
	CreateTree(ctx context.Context, owner, repo, baseTree string, entries []TreeEntry) (string, error)

	// CreateBlob creates a git blob with the given content.
	CreateBlob(ctx context.Context, owner, repo string, content []byte, encoding string) (string, error)

	// GetPullRequest retrieves a pull request by number.
	GetPullRequest(ctx context.Context, owner, repo string, number int) (*gogithub.PullRequest, error)

	// ListPullRequests lists pull requests in a repository.
	ListPullRequests(ctx context.Context, owner, repo string, opts *ListPullRequestsOptions) ([]*gogithub.PullRequest, error)

	// CreatePullRequest creates a new pull request.
	CreatePullRequest(ctx context.Context, owner, repo string, input *CreatePullRequestInput) (*gogithub.PullRequest, error)

	// UpdatePullRequest updates a pull request.
	UpdatePullRequest(ctx context.Context, owner, repo string, number int, input *UpdatePullRequestInput) (*gogithub.PullRequest, error)

	// MergePullRequest merges a pull request.
	MergePullRequest(ctx context.Context, owner, repo string, number int, opts *MergePullRequestOptions) (*gogithub.MergeResult, error)

	// ListPullRequestFiles lists files changed in a pull request.
	ListPullRequestFiles(ctx context.Context, owner, repo string, number int) ([]*gogithub.CommitFile, error)

	// GetPullRequestDiff gets the diff for a pull request.
	GetPullRequestDiff(ctx context.Context, owner, repo string, number int) (string, error)

	// GetPullRequestPatch gets the patch for a pull request.
	GetPullRequestPatch(ctx context.Context, owner, repo string, number int) (string, error)

	// CreatePullRequestReview creates a review on a pull request.
	CreatePullRequestReview(ctx context.Context, owner, repo string, number int, input *CreateReviewInput) (*gogithub.PullRequestReview, error)

	// ListPullRequestReviews lists reviews on a pull request.
	ListPullRequestReviews(ctx context.Context, owner, repo string, number int) ([]*gogithub.PullRequestReview, error)

	// RequestReviewers requests reviewers for a pull request.
	RequestReviewers(ctx context.Context, owner, repo string, number int, reviewers, teamReviewers []string) (*gogithub.PullRequest, error)

	// CreatePullRequestComment creates a comment on a pull request diff.
	CreatePullRequestComment(ctx context.Context, owner, repo string, number int, input *CreatePRCommentInput) (*gogithub.PullRequestComment, error)

	// ListPullRequestComments lists comments on a pull request.
	ListPullRequestComments(ctx context.Context, owner, repo string, number int) ([]*gogithub.PullRequestComment, error)

	// GetIssue retrieves an issue by number.
	GetIssue(ctx context.Context, owner, repo string, number int) (*gogithub.Issue, error)

	// ListIssues lists issues in a repository.
	ListIssues(ctx context.Context, owner, repo string, opts *ListIssuesOptions) ([]*gogithub.Issue, error)

	// CreateIssue creates a new issue.
	CreateIssue(ctx context.Context, owner, repo string, input *CreateIssueInput) (*gogithub.Issue, error)

	// UpdateIssue updates an existing issue.
	UpdateIssue(ctx context.Context, owner, repo string, number int, input *UpdateIssueInput) (*gogithub.Issue, error)

	// CreateIssueComment creates a comment on an issue or pull request.
	CreateIssueComment(ctx context.Context, owner, repo string, number int, body string) (*gogithub.IssueComment, error)

	// GetCheckRun retrieves a check run by ID.
	GetCheckRun(ctx context.Context, owner, repo string, checkRunID int64) (*gogithub.CheckRun, error)

	// ListCheckRuns lists check runs for a git reference.
	ListCheckRuns(ctx context.Context, owner, repo, ref string) ([]*gogithub.CheckRun, error)

	// ListCheckSuites lists check suites for a git reference.
	ListCheckSuites(ctx context.Context, owner, repo, ref string) ([]*gogithub.CheckSuite, error)

	// GetRelease retrieves a release by ID.
	GetRelease(ctx context.Context, owner, repo string, id int64) (*gogithub.Release, error)

	// GetLatestRelease retrieves the latest release.
	GetLatestRelease(ctx context.Context, owner, repo string) (*gogithub.Release, error)

	// GetReleaseByTag retrieves a release by its tag name.
	GetReleaseByTag(ctx context.Context, owner, repo, tag string) (*gogithub.Release, error)

	// ListReleases lists all releases in a repository.
	ListReleases(ctx context.Context, owner, repo string) ([]*gogithub.Release, error)

	// CreateRelease creates a new release.
	CreateRelease(ctx context.Context, owner, repo string, input *CreateReleaseInput) (*gogithub.Release, error)

	// UpdateRelease updates a release.
	UpdateRelease(ctx context.Context, owner, repo string, id int64, input *UpdateReleaseInput) (*gogithub.Release, error)

	// DeleteRelease deletes a release.
	DeleteRelease(ctx context.Context, owner, repo string, id int64) error

	// ListReleaseAssets lists assets for a release.
	ListReleaseAssets(ctx context.Context, owner, repo string, releaseID int64) ([]*gogithub.ReleaseAsset, error)

	// SearchIssues searches for issues and pull requests.
	SearchIssues(ctx context.Context, query string, opts *SearchOptions) (*gogithub.IssueSearchResult, error)

	// SearchCode searches for code in repositories.
	SearchCode(ctx context.Context, query string, opts *SearchOptions) (*gogithub.CodeSearchResult, error)

	// GetContributorStats gets contribution statistics for a repository.
	GetContributorStats(ctx context.Context, owner, repo string) ([]*gogithub.ContributorStats, error)

	// ListUserEvents lists activity events performed by a user (their public
	// timeline). GitHub's Events API only returns the most recent ~300 events.
	ListUserEvents(ctx context.Context, username string, opts *ListUserEventsOptions) ([]*gogithub.Event, error)

	// Raw returns the underlying go-github client for advanced use cases.
	// WARNING: Using this couples your code to a specific go-github version.
	// The returned value is *github.Client from the go-github package.
	Raw() any
}

type ClientOptions struct {
	// Token is the GitHub personal access token.
	Token string
	// BaseURL is the GitHub API base URL (for GitHub Enterprise).
	// Leave empty for github.com.
	BaseURL string
	// UploadURL is the GitHub upload URL (for GitHub Enterprise).
	// Leave empty for github.com.
	UploadURL string
}

type CommitAuthor struct {
	Name  string
	Email string
	Date  *time.Time
}

type CreateCommitOptions struct {
	Message string
	Tree    string   // Tree SHA
	Parents []string // Parent commit SHAs
	Author  *CommitAuthor
}

type CreateFileOptions struct {
	Content []byte
	Message string
	Branch  string // Optional: defaults to repository's default branch
	Author  *CommitAuthor
}

type CreateForkOptions struct {
	Organization  string // Fork to this org instead of user's account
	Name          string // Custom name for the fork
	DefaultBranch bool   // Only fork the default branch
}

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

type CreatePRCommentInput struct {
	Body     string
	CommitID string
	Path     string
	Line     int
	Side     string // "LEFT" or "RIGHT"
}

type CreatePullRequestInput struct {
	// Title is the PR title (required).
	Title string
	// Head is the branch containing changes (required).
	Head string
	// Base is the branch to merge into (required).
	Base string
	// Body is the PR description.
	Body string
	// Draft creates the PR as a draft.
	Draft bool
	// MaintainerCanModify allows maintainers to push to the head branch.
	MaintainerCanModify bool
}

type CreateReleaseInput struct {
	TagName              string
	TargetCommitish      string
	Name                 string
	Body                 string
	Draft                bool
	Prerelease           bool
	GenerateReleaseNotes bool
}

type CreateReviewInput struct {
	Event string // "APPROVE", "REQUEST_CHANGES", or "COMMENT"
	Body  string
}

type DeleteFileOptions struct {
	Branch string
	Author *CommitAuthor
}

type ListCommitsOptions struct {
	// SHA is the branch name or commit SHA to start from.
	SHA string
	// Path filters to commits containing this file path.
	Path string
	// Since filters to commits after this time.
	Since *time.Time
	// Until filters to commits before this time.
	Until *time.Time
	// Author filters to commits by this author (GitHub login or email).
	Author string
}

type ListIssuesOptions struct {
	State     string   // "open", "closed", or "all". Default: "open"
	Labels    []string // Filter by labels
	Sort      string   // "created", "updated", "comments". Default: "created"
	Direction string   // "asc" or "desc". Default: "desc"
	Since     *time.Time
	PerPage   int
	Page      int
}

type ListPullRequestsOptions struct {
	// State filters by state: "open", "closed", or "all". Default: "open".
	State string
	// Head filters by head branch (format: "user:branch" or "org:branch").
	Head string
	// Base filters by base branch name.
	Base string
	// Sort specifies the sort order: "created", "updated", "popularity", "long-running".
	Sort string
	// Direction specifies sort direction: "asc" or "desc".
	Direction string
}

type ListUserEventsOptions struct {
	// PublicOnly restricts results to publicly visible events. When false and
	// the request is authenticated as username, private events are also included.
	PublicOnly bool
}

type MergePullRequestOptions struct {
	CommitTitle   string
	CommitMessage string
	MergeMethod   string // "merge", "squash", or "rebase"
	SHA           string // Expected head SHA for optimistic locking
}

type SearchOptions struct {
	Sort    string // "comments", "reactions", "created", "updated", etc.
	Order   string // "asc" or "desc"
	PerPage int
	Page    int
}

type TreeEntry struct {
	Path    string
	Mode    string // "100644" (file), "100755" (executable), "040000" (directory), "160000" (submodule), "120000" (symlink)
	Type    string // "blob", "tree", or "commit"
	SHA     string // SHA of existing blob, or empty to use Content
	Content string // File content (creates new blob)
}

type UpdateFileOptions struct {
	Content []byte
	SHA     string // Current file SHA (required for optimistic locking)
	Message string
	Branch  string
	Author  *CommitAuthor
}

type UpdateIssueInput struct {
	Title     *string
	Body      *string
	State     *string // "open" or "closed"
	Labels    []string
	Assignees []string
	Milestone *int
}

type UpdatePullRequestInput struct {
	Title               *string
	Body                *string
	State               *string // "open" or "closed"
	Base                *string
	MaintainerCanModify *bool
}

type UpdateReleaseInput struct {
	TagName         *string
	TargetCommitish *string
	Name            *string
	Body            *string
	Draft           *bool
	Prerelease      *bool
}